Notation used in Ruby API documentation
Module: db
Description: A cell mapping (source to target layout)
A cell mapping is an association of cells in two layouts forming pairs of cells, i.e. one cell corresponds to another cell in the other layout. The CellMapping object describes the mapping of cells of a source layout B to a target layout A. The cell mapping object is basically a table associating a cell in layout B with a cell in layout A.
The cell mapping is of particular interest for providing the cell mapping recipe in Cell#copy_tree_shapes or Cell#move_tree_shapes.
The mapping object is used to create and hold that table. There are three basic modes in which a table can be generated:
'full' refers to the way cells are treated which are not mentioned. In the 'full' versions, cells for which no mapping is established explicitly - specifically all child cells in top-level identity modes - are created in the target layout and instantiated according to their source layout hierarchy. Then, these new cells become targets of the respective source cells. In the plain version (without 'full' cells), no additional cells are created. For the case of Layout#copy_tree_shapes cells not explicitly mapped are flattened. Hence for example, for_single_cell will flatten all children of the source cell during Layout#copy_tree_shapes or Layout#move_tree_shapes.
Top-level identity means that only one cell (the top cell) is regarded identical. All child cells are not considered identical. In full mode (see below), this will create a new, identical cell tree below the top cell in layout A.
Geometrical identity is defined by the exact identity of the set of expanded instances in each starting cell. Therefore, when a cell is mapped to another cell, shapes can be transferred from one cell to another while effectively rendering the same flat geometry (in the context of the given starting cells). Location identity is basically the safest way to map cells from one hierarchy into another, because it preserves the flat shape geometry. However in some cases the algorithm may find multiple mapping candidates. In that case it will make a guess about what mapping to choose.
Name identity means that cells are identified by their names - for a source cell in layer B, a target cell with the same name is looked up in the target layout A and a mapping is created if a cell with the same name is found. However, name identity does not mean that the cells are actually equivalent because they may be placed differently. Hence, cell mapping by name is not a good choice when it is important to preserve the shape geometry of a layer.
A cell might not be mapped to another cell which basically means that there is no corresponding cell. In this case, flattening to the next mapped cell is an option to transfer geometries despite the missing mapping. You can enforce a mapping by using the mapping generator methods in 'full' mode, i.e. from_names_full or from_geometry_full. These versions will create new cells and their corresponding instances in the target layout if no suitable target cell is found.
This is a simple example for a cell mapping preserving the hierarchy of the source cell and creating a hierarchy copy in the top cell of the target layout ('hierarchical merge'):
cell_names = [ "A", "B", "C" ]
source = RBA::Layout::new
source.read("input.gds")
target = RBA::Layout::new
target_top = target.create_cell("IMPORTED")
cm = RBA::CellMapping::new
# Copies the source layout hierarchy into the target top cell:
cm.for_single_cell_full(target_top, source.top_cell)
target.copy_tree_shapes(source, cm)
Without 'full', the effect is move-with-flattening (note we're using 'move' in this example):
cell_names = [ "A", "B", "C" ]
source = RBA::Layout::new
source.read("input.gds")
target = RBA::Layout::new
target_top = target.create_cell("IMPORTED")
cm = RBA::CellMapping::new
# Flattens the source layout hierarchy into the target top cell:
cm.for_single_cell(target_top, source.top_cell)
target.move_tree_shapes(source, cm)
This is another example for using CellMapping in multiple top cell identity mode. It extracts cells 'A', 'B' and 'C' from one layout and copies them to another. It will also copy all shapes and all child cells. Child cells which are shared between the three initial cells will be shared in the target layout too.
cell_names = [ "A", "B", "C" ]
source = RBA::Layout::new
source.read("input.gds")
target = RBA::Layout::new
source_cells = cell_names.collect { |n| source.cell_by_name(n) }
target_cells = cell_names.collect { |n| target.create_cell(n) }
cm = RBA::CellMapping::new
cm.for_multi_cells_full(target_cells, source_cells)
target.copy_tree_shapes(source, cm)
| new CellMapping ptr | new | Creates a new object of this class |
| [const] | CellMapping 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. | ||
| void | assign | (const CellMapping other) | Assigns another object to self | |
| [const] | unsigned int | cell_mapping | (unsigned int cell_index_b) | Determines cell mapping of a layout_b cell to the corresponding layout_a cell. |
| void | clear | Clears the mapping. | ||
| [const] | new CellMapping ptr | dup | Creates a copy of self | |
| void | for_multi_cells | (const Layout layout_a, unsigned int[] cell_indexes_a, const Layout layout_b, unsigned int[] cell_indexes_b) | Initializes the cell mapping for top-level identity | |
| void | for_multi_cells | (Cell ptr[] cell_a, const Cell ptr[] cell_b) | Initializes the cell mapping for top-level identity | |
| unsigned int[] | for_multi_cells_full | (Layout layout_a, unsigned int[] cell_indexes_a, const Layout layout_b, unsigned int[] cell_indexes_b) | Initializes the cell mapping for top-level identity in full mapping mode | |
| unsigned int[] | for_multi_cells_full | (Cell ptr[] cell_a, const Cell ptr[] cell_b) | Initializes the cell mapping for top-level identity in full mapping mode | |
| void | for_single_cell | (const Layout layout_a, unsigned int cell_index_a, const Layout layout_b, unsigned int cell_index_b) | Initializes the cell mapping for top-level identity | |
| void | for_single_cell | (Cell cell_a, const Cell cell_b) | Initializes the cell mapping for top-level identity | |
| unsigned int[] | for_single_cell_full | (Layout layout_a, unsigned int cell_index_a, const Layout layout_b, unsigned int cell_index_b) | Initializes the cell mapping for top-level identity in full mapping mode | |
| unsigned int[] | for_single_cell_full | (Cell cell_a, const Cell cell_b) | Initializes the cell mapping for top-level identity in full mapping mode | |
| void | from_geometry | (const Layout layout_a, unsigned int cell_index_a, const Layout layout_b, unsigned int cell_index_b) | Initializes the cell mapping using the geometrical identity | |
| void | from_geometry | (Cell cell_a, const Cell cell_b) | Initializes the cell mapping using the geometrical identity | |
| unsigned int[] | from_geometry_full | (Layout layout_a, unsigned int cell_index_a, const Layout layout_b, unsigned int cell_index_b) | Initializes the cell mapping using the geometrical identity in full mapping mode | |
| unsigned int[] | from_geometry_full | (Cell cell_a, const Cell cell_b) | Initializes the cell mapping using the geometrical identity in full mapping mode | |
| void | from_names | (const Layout layout_a, unsigned int cell_index_a, const Layout layout_b, unsigned int cell_index_b) | Initializes the cell mapping using the name identity | |
| void | from_names | (Cell cell_a, const Cell cell_b) | Initializes the cell mapping using the name identity | |
| unsigned int[] | from_names_full | (Layout layout_a, unsigned int cell_index_a, const Layout layout_b, unsigned int cell_index_b) | Initializes the cell mapping using the name identity in full mapping mode | |
| unsigned int[] | from_names_full | (Cell cell_a, const Cell cell_b) | Initializes the cell mapping using the name identity in full mapping mode | |
| [const] | bool | has_mapping? | (unsigned int cell_index_b) | Returns as value indicating whether a cell of layout_b has a mapping to a layout_a cell. |
| void | map | (unsigned int cell_index_b, unsigned int cell_index_a) | Explicitly specifies a mapping. | |
| [const] | map<unsigned int,unsigned int> | table | Returns the mapping table. |
| unsigned int | DropCell | A constant indicating the request to drop a cell |
| 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 |
DropCell | Signature: [static] unsigned int DropCell Description: A constant indicating the request to drop a cell If used as a pseudo-target for the cell mapping, this index indicates that the cell shall be dropped rather than created on the target side or skipped by flattening. Instead, all shapes of this cell are discarded and its children are not translated unless explicitly requested or if required are children for other cells. This constant has been introduced in version 0.25. Python specific notes: | ||||||||||
_const_cast | Signature: [const] CellMapping 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. | ||||||||||
assign | Signature: void assign (const CellMapping other) Description: Assigns another object to self | ||||||||||
cell_mapping | Signature: [const] unsigned int cell_mapping (unsigned int cell_index_b) Description: Determines cell mapping of a layout_b cell to the corresponding layout_a cell.
Note that the returned index can be DropCell to indicate the cell shall be dropped. | ||||||||||
clear | Signature: void clear Description: Clears the mapping. This method has been introduced in version 0.23. | ||||||||||
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. | ||||||||||
dup | Signature: [const] new CellMapping ptr dup Description: Creates a copy of self Python specific notes: | ||||||||||
for_multi_cells | (1) Signature: void for_multi_cells (const Layout layout_a, unsigned int[] cell_indexes_a, const Layout layout_b, unsigned int[] cell_indexes_b) Description: Initializes the cell mapping for top-level identity
The cell mapping is created for cells from cell_indexes_b to cell from cell_indexes_a in the respective layouts. This method clears the mapping and creates one for each cell pair from cell_indexes_b vs. cell_indexes_a. If used for Layout#copy_tree_shapes or Layout#move_tree_shapes, this cell mapping will essentially flatten the source cells in the target layout. This method is equivalent to clear, followed by map(cell_index_a, cell_index_b) for each cell pair. This method has been introduced in version 0.27. | ||||||||||
(2) Signature: void for_multi_cells (Cell ptr[] cell_a, const Cell ptr[] cell_b) Description: Initializes the cell mapping for top-level identity
This is a convenience version which uses cell references instead of layout/cell index combinations. It has been introduced in version 0.28. | |||||||||||
for_multi_cells_full | (1) Signature: unsigned int[] for_multi_cells_full (Layout layout_a, unsigned int[] cell_indexes_a, const Layout layout_b, unsigned int[] cell_indexes_b) Description: Initializes the cell mapping for top-level identity in full mapping mode
The cell mapping is created for cells from cell_indexes_b to cell from cell_indexes_a in the respective layouts. This method clears the mapping and creates one for each cell pair from cell_indexes_b vs. cell_indexes_a. In addition and in contrast to for_multi_cells, this method completes the mapping by adding all the child cells of all cells in cell_indexes_b to layout_a and creating the proper instances. This method has been introduced in version 0.27. | ||||||||||
(2) Signature: unsigned int[] for_multi_cells_full (Cell ptr[] cell_a, const Cell ptr[] cell_b) Description: Initializes the cell mapping for top-level identity in full mapping mode
This is a convenience version which uses cell references instead of layout/cell index combinations. It has been introduced in version 0.28. | |||||||||||
for_single_cell | (1) Signature: void for_single_cell (const Layout layout_a, unsigned int cell_index_a, const Layout layout_b, unsigned int cell_index_b) Description: Initializes the cell mapping for top-level identity
The cell mapping is created for cell_b to cell_a in the respective layouts. This method clears the mapping and creates one for the single cell pair. If used for Cell#copy_tree or Cell#move_tree, this cell mapping will essentially flatten the cell. This method is equivalent to clear, followed by map(cell_index_a, cell_index_b). This method has been introduced in version 0.23. | ||||||||||
(2) Signature: void for_single_cell (Cell cell_a, const Cell cell_b) Description: Initializes the cell mapping for top-level identity
This is a convenience version which uses cell references instead of layout/cell index combinations. It has been introduced in version 0.28. | |||||||||||
for_single_cell_full | (1) Signature: unsigned int[] for_single_cell_full (Layout layout_a, unsigned int cell_index_a, const Layout layout_b, unsigned int cell_index_b) Description: Initializes the cell mapping for top-level identity in full mapping mode
The cell mapping is created for cell_b to cell_a in the respective layouts. This method clears the mapping and creates one for the single cell pair. In addition and in contrast to for_single_cell, this method completes the mapping by adding all the child cells of cell_b to layout_a and creating the proper instances. This method has been introduced in version 0.23. | ||||||||||
(2) Signature: unsigned int[] for_single_cell_full (Cell cell_a, const Cell cell_b) Description: Initializes the cell mapping for top-level identity in full mapping mode
This is a convenience version which uses cell references instead of layout/cell index combinations. It has been introduced in version 0.28. | |||||||||||
from_geometry | (1) Signature: void from_geometry (const Layout layout_a, unsigned int cell_index_a, const Layout layout_b, unsigned int cell_index_b) Description: Initializes the cell mapping using the geometrical identity
The cell mapping is created for cells below cell_a and cell_b in the respective layouts. This method employs geometrical identity to derive mappings for the child cells of the starting cell in layout A and B. If the geometrical identity is ambiguous, the algorithm will make an arbitrary choice. This method has been introduced in version 0.23. | ||||||||||
(2) Signature: void from_geometry (Cell cell_a, const Cell cell_b) Description: Initializes the cell mapping using the geometrical identity
This is a convenience version which uses cell references instead of layout/cell index combinations. It has been introduced in version 0.28. | |||||||||||
from_geometry_full | (1) Signature: unsigned int[] from_geometry_full (Layout layout_a, unsigned int cell_index_a, const Layout layout_b, unsigned int cell_index_b) Description: Initializes the cell mapping using the geometrical identity in full mapping mode
The cell mapping is created for cells below cell_a and cell_b in the respective layouts. This method employs geometrical identity to derive mappings for the child cells of the starting cell in layout A and B. If the geometrical identity is ambiguous, the algorithm will make an arbitrary choice. Full mapping means that cells which are not found in the target layout A are created there plus their corresponding instances are created as well. The returned list will contain the indexes of all cells created for that reason. This method has been introduced in version 0.23. | ||||||||||
(2) Signature: unsigned int[] from_geometry_full (Cell cell_a, const Cell cell_b) Description: Initializes the cell mapping using the geometrical identity in full mapping mode
This is a convenience version which uses cell references instead of layout/cell index combinations. It has been introduced in version 0.28. | |||||||||||
from_names | (1) Signature: void from_names (const Layout layout_a, unsigned int cell_index_a, const Layout layout_b, unsigned int cell_index_b) Description: Initializes the cell mapping using the name identity
The cell mapping is created for cells below cell_a and cell_b in the respective layouts. This method employs name identity to derive mappings for the child cells of the starting cell in layout A and B. This method has been introduced in version 0.23. | ||||||||||
(2) Signature: void from_names (Cell cell_a, const Cell cell_b) Description: Initializes the cell mapping using the name identity
This is a convenience version which uses cell references instead of layout/cell index combinations. It has been introduced in version 0.28. | |||||||||||
from_names_full | (1) Signature: unsigned int[] from_names_full (Layout layout_a, unsigned int cell_index_a, const Layout layout_b, unsigned int cell_index_b) Description: Initializes the cell mapping using the name identity in full mapping mode
The cell mapping is created for cells below cell_a and cell_b in the respective layouts. This method employs name identity to derive mappings for the child cells of the starting cell in layout A and B. Full mapping means that cells which are not found in the target layout A are created there plus their corresponding instances are created as well. The returned list will contain the indexes of all cells created for that reason. This method has been introduced in version 0.23. | ||||||||||
(2) Signature: unsigned int[] from_names_full (Cell cell_a, const Cell cell_b) Description: Initializes the cell mapping using the name identity in full mapping mode
This is a convenience version which uses cell references instead of layout/cell index combinations. It has been introduced in version 0.28. | |||||||||||
has_mapping? | Signature: [const] bool has_mapping? (unsigned int cell_index_b) Description: Returns as value indicating whether a cell of layout_b has a mapping to a layout_a cell.
Note that if the cell is supposed to be dropped (see DropCell), the respective source cell will also be regarded "mapped", so has_mapping? will return true in this case. | ||||||||||
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. | ||||||||||
map | Signature: void map (unsigned int cell_index_b, unsigned int cell_index_a) Description: Explicitly specifies a mapping.
Beside using the mapping generator algorithms provided through from_names and from_geometry, it is possible to explicitly specify cell mappings using this method. This method has been introduced in version 0.23. | ||||||||||
new | Signature: [static] new CellMapping ptr new Description: Creates a new object of this class Python specific notes: | ||||||||||
table | Signature: [const] map<unsigned int,unsigned int> table Description: Returns the mapping table. The mapping table is a dictionary where the keys are source layout cell indexes and the values are the target layout cell indexes. Note that the target cell index can be DropCell to indicate that a cell is supposed to be dropped. This method has been introduced in version 0.25. |