API reference - Class CellMapping

Notation used in Ruby API documentation

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 mapping object is used to create and hold that table. There are three basic modes in which a table can be generated:

  • Top-level identity
  • Geometrical identity
  • Name identity

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.

CellMapping objects play a role mainly in the hierarchical copy or move operations of Layout. However, use is not restricted to these applications.

Public constructors

new CellMapping ptrnewCreates a new object of this class

Public methods

void_createEnsures the C++ object is created
void_destroyExplicitly destroys the object
[const]bool_destroyed?Returns a value indicating whether the object was already destroyed
[const]bool_is_const_object?Returns a value indicating whether the reference is a const reference
void_manageMarks the object as managed by the script side.
void_unmanageMarks the object as no longer owned by the script side.
voidassign(const CellMapping other)Assigns another object to self
[const]unsigned intcell_mapping(unsigned int cell_index_b)Determines cell mapping of a layout_b cell to the corresponding layout_a cell.
voidclearClears the mapping.
[const]new CellMapping ptrdupCreates a copy of self
voidfor_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
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
voidfrom_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
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
voidfrom_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
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
[const]boolhas_mapping?(unsigned int cell_index_b)Returns as value indicating whether a cell of layout_b has a mapping to a layout_a cell.
voidmap(unsigned int cell_index_b,
unsigned int cell_index_a)
Explicitly specifies a mapping.
[const]map<unsigned int,unsigned int>tableReturns the mapping table.

Public static methods and constants

unsigned intDropCellA constant indicating the reques to drop a cell

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

DropCell

Signature: [static] unsigned int DropCell

Description: A constant indicating the reques 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 it's children are not translated unless explicitly requested or if required are children for other cells.

This constant has been introduced in version 0.25.

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

cell_index_b:The index of the cell in layout_b whose mapping is requested.
Returns:The cell index in layout_a.

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

destroy

Signature: void destroy

Description: Explicitly destroys the object

Use of this method is deprecated. Use _destroy instead

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

dup

Signature: [const] new CellMapping ptr dup

Description: Creates a copy of self

for_single_cell

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

layout_a:The target layout.
cell_index_a:The index of the target cell.
layout_b:The source layout.
cell_index_b:The index of the source cell.

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.

for_single_cell_full

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

layout_a:The target layout.
cell_index_a:The index of the target cell.
layout_b:The source layout.
cell_index_b:The index of the source cell.

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.

from_geometry

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

layout_a:The target layout.
cell_index_a:The index of the target starting cell.
layout_b:The source layout.
cell_index_b:The index of the source starting cell.

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.

from_geometry_full

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

layout_a:The target layout.
cell_index_a:The index of the target starting cell.
layout_b:The source layout.
cell_index_b:The index of the source starting cell.
Returns:A list of indexes of cells created.

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.

from_names

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

layout_a:The target layout.
cell_index_a:The index of the target starting cell.
layout_b:The source layout.
cell_index_b:The index of the source starting cell.

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.

from_names_full

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

layout_a:The target layout.
cell_index_a:The index of the target starting cell.
layout_b:The source layout.
cell_index_b:The index of the source starting cell.
Returns:A list of indexes of cells created.

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.

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.

cell_index_b:The index of the cell in layout_b whose mapping is requested.
Returns:true, if the cell has a mapping

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

map

Signature: void map (unsigned int cell_index_b,unsigned int cell_index_a)

Description: Explicitly specifies a mapping.

cell_index_b:The index of the cell in layout B (the "source")
cell_index_a:The index of the cell in layout A (the "target") - this index can be DropCell

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:
This method is the default initializer of the object

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.