API reference - Class Cell

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

basic_name

Signature: [const] string basic_name

Description: Returns the name of the library or PCell or the real name of the cell

For non-proxy cells (see is_proxy?), this method simply returns the cell name. For proxy cells, this method returns the PCell's definition name or the library cell name. This name may differ from the actual cell's name because to ensure that cell names are unique, KLayout may assign different names to the actual cell compared to the source cell.

This method has been introduced in version 0.22.

bbox

Signature: [const] Box bbox

Description: Gets the bounding box of the cell

The bounding box is computed over all layers. To compute the bounding box over single layers, use bbox_per_layer.

bbox_per_layer

Signature: [const] Box bbox_per_layer (unsigned int layer_index)

Description: Gets the per-layer bounding box of the cell

The bounding box is the box enclosing all shapes on the given layer.

begin_shapes_rec

Signature: [const] RecursiveShapeIterator begin_shapes_rec (unsigned int layer)

Description: Delivers a recursive shape iterator for the shapes below the cell on the given layer

For details see the description of the RecursiveShapeIterator class.

This method has been added in version 0.23.

begin_shapes_rec_overlapping

Signature: [const] RecursiveShapeIterator begin_shapes_rec_overlapping (unsigned int layer,Box region)

Description: Delivers a recursive shape iterator for the shapes below the cell on the given layer using a region search

For details see the description of the RecursiveShapeIterator class. This version gives an iterator delivering shapes whose bounding box overlaps the given region.

This method has been added in version 0.23.

Signature: [const] RecursiveShapeIterator begin_shapes_rec_overlapping (unsigned int layer,DBox region)

Description: Delivers a recursive shape iterator for the shapes below the cell on the given layer using a region search, with the region given in micrometer units

For details see the description of the RecursiveShapeIterator class. This version gives an iterator delivering shapes whose bounding box overlaps the given region.

This variant has been added in version 0.25.

begin_shapes_rec_touching

Signature: [const] RecursiveShapeIterator begin_shapes_rec_touching (unsigned int layer,Box region)

Description: Delivers a recursive shape iterator for the shapes below the cell on the given layer using a region search

For details see the description of the RecursiveShapeIterator class. This version gives an iterator delivering shapes whose bounding box touches the given region.

This method has been added in version 0.23.

Signature: [const] RecursiveShapeIterator begin_shapes_rec_touching (unsigned int layer,DBox region)

Description: Delivers a recursive shape iterator for the shapes below the cell on the given layer using a region search, with the region given in micrometer units

For details see the description of the RecursiveShapeIterator class. This version gives an iterator delivering shapes whose bounding box touches the given region.

This variant has been added in version 0.25.

called_cells

Signature: [const] unsigned int[] called_cells

Description: Gets a list of all called cells

This method determines all cells which are called either directly or indirectly by the cell. It returns an array of cell indexes. Use the 'cell' method of Layout to retrieve the corresponding Cell object.

This method has been introduced in version 0.19.

caller_cells

Signature: [const] unsigned int[] caller_cells

Description: Gets a list of all caller cells

This method determines all cells which call this cell either directly or indirectly. It returns an array of cell indexes. Use the 'cell' method of Layout to retrieve the corresponding Cell object.

This method has been introduced in version 0.19.

cell_index

Signature: [const] unsigned int cell_index

Description: Gets the cell index

change_pcell_parameter

Signature: Instance change_pcell_parameter (const Instance instance,string name,variant value)

Description: Changes a single parameter for an individual PCell instance given by name

This will set the PCell parameter named 'name' to the given value for the instance addressed by 'instance'. If no parameter with that name exists, the method will do nothing.

This method has been introduced in version 0.23.

change_pcell_parameters

Signature: Instance change_pcell_parameters (const Instance instance,map<string,variant> dict)

Description: Changes the given parameter for an individual PCell instance

This version receives a dictionary of names and values. It will change the parameters given by the names to the values given by the values of the dictionary. The functionality is similar to the same function with an array, but more convenient to use. Values with unknown names are ignored.

This method has been introduced in version 0.24.

Signature: Instance change_pcell_parameters (const Instance instance,variant[] parameters)

Description: Changes the parameters for an individual PCell instance

If necessary, this method creates a new variant and replaces the given instance by an instance of this variant.

The parameters are given in the order the parameters are declared. Use pcell_declaration on the instance to get the PCell declaration object of the cell. That PCellDeclaration object delivers the parameter declaration with it's 'get_parameters' method. Each parameter in the variant list passed to the second list of values corresponds to one parameter declaration.

There is a more convenient method (change_pcell_parameter) that changes a single parameter by name.

This method has been introduced in version 0.22.

child_cells

Signature: [const] unsigned long child_cells

Description: Gets the number of child cells

The number of child cells (not child instances!) is returned. CAUTION: this method is SLOW, in particular if many instances are present.

child_instances

Signature: [const] unsigned long child_instances

Description: Gets the number of child instances

clear

Signature: void clear (unsigned int layer_index)

Description: Clears the shapes on the given layer

Signature: void clear

Description: Clears the cell (deletes shapes and instances)

This method has been introduced in version 0.23.

clear_insts

Signature: void clear_insts

Description: Clears the instance list

clear_shapes

Signature: void clear_shapes

Description: Clears all shapes in the cell

copy

Signature: void copy (unsigned int src,unsigned int dest)

Description: Copies the shapes from the source to the target layer

The destination layer is not overwritten. Instead, the shapes are added to the shapes of the destination layer. If source are target layer are identical, this method does nothing. This method will copy shapes within the cell. To copy shapes from another cell this cell, use the copy method with the cell parameter.

This method has been introduced in version 0.19.

Signature: void copy (Cell ptr src_cell,unsigned int src_layer,unsigned int dest)

Description: Copies shapes from another cell to the target layern this cell

This method will copy all shapes on layer 'src_layer' of cell 'src_cell' to the layer 'dest' of this cell. The destination layer is not overwritten. Instead, the shapes are added to the shapes of the destination layer. If the source cell lives in a layout with a different database unit than that current cell is in, the shapes will be transformed accordingly. The same way, shape properties are transformed as well. Note that the shape transformation may require rounding to smaller coordinates. This may result in a slight distortion of the original shapes, in particular when transforming into a layout with a bigger database unit.

copy_instances

Signature: void copy_instances (const Cell source_cell)

Description: Copies the instances of child cells in the source cell to this cell

The source cell must reside in the same layout than this cell. The instances of child cells inside the source cell are copied to this cell. No new cells are created, just new instances are created to already existing cells in the target cell.

The instances will be added to any existing instances in the cell.

More elaborate methods of copying hierarchy trees between layouts or duplicating trees are provided through the copy_tree_shapes (in cooperation with the CellMapping class) or copy_tree methods.

This method has been added in version 0.23.

copy_shapes

Signature: void copy_shapes (const Cell source_cell)

Description: Copies the shapes from the given cell into this cell

All shapes are copied from the source cell to this cell. Instances are not copied.

The source cell can reside in a different layout. In this case, the shapes are copied over from the other layout into this layout. Database unit conversion is done automatically if the database units differ between the layouts. Note that this may lead to grid snapping effects if the database unit of the target layout is not an integer fraction of the source layout.

If source and target layout are different, the layers of the source and target layout are identified by their layer/datatype number or name (if no layer/datatype is present). The shapes will be added to any shapes already in the cell.

This method has been added in version 0.23.

Signature: void copy_shapes (const Cell source_cell,const LayerMapping layer_mapping)

Description: Copies the shapes from the given cell into this cell

All shapes on layers specified in the layer mapping object are copied from the source cell to this cell. Instances are not copied. The target layer is taken from the mapping table.

The shapes will be added to any shapes already in the cell.

This method has been added in version 0.23.

copy_tree

Signature: unsigned int[] copy_tree (const Cell source_cell)

Description: Copies the cell tree of the given cell into this cell

The complete cell tree of the source cell is copied to the target cell plus all shapes in that tree are copied as well. This method will basically duplicate the cell tree of the source cell.

The source cell may reside in a separate layout. This method therefore provides a way to copy over complete cell trees from one layout to another.

The shapes and instances will be added to any shapes or instances already in the cell.

This method has been added in version 0.23.

copy_tree_shapes

Signature: void copy_tree_shapes (const Cell source_cell,const CellMapping cell_mapping)

Description: Copies the shapes from the given cell and the cell tree below into this cell or subcells of this cell

This method is provided if source and target cell reside in different layouts. If will copy the shapes from all cells below the given source cell, but use a cell mapping object that provides a specification how cells are identified between the layouts. Cells in the source tree, for which no mapping is provided, will be flattened - their shapes will be propagated into parent cells for which a mapping is provided.

The cell mapping object provides various methods to map cell trees between layouts. See the CellMapping class for details about the mapping methods available. The cell mapping object is also responsible for creating a proper hierarchy of cells in the target layout if that is required.

Layers are identified between the layouts by the layer/datatype number of name if no layer/datatype number is present.

The shapes copied will be added to any shapes already in the cells.

This method has been added in version 0.23.

Signature: void copy_tree_shapes (const Cell source_cell,const CellMapping cell_mapping,const LayerMapping layer_mapping)

Description: Copies the shapes from the given cell and the cell tree below into this cell or subcells of this cell with layer mapping

This method is provided if source and target cell reside in different layouts. If will copy the shapes from all cells below the given source cell, but use a cell mapping object that provides a specification how cells are identified between the layouts. Cells in the source tree, for which no mapping is provided, will be flattened - their shapes will be propagated into parent cells for which a mapping is provided.

The cell mapping object provides various methods to map cell trees between layouts. See the CellMapping class for details about the mapping methods available. The cell mapping object is also responsible for creating a proper hierarchy of cells in the target layout if that is required.

In addition, the layer mapping object can be specified which maps source to target layers. This feature can be used to restrict the copy operation to a subset of layers or to convert shapes to different layers in that step.

The shapes copied will be added to any shapes already in the cells.

This method has been added in version 0.23.

create

Signature: void create

Description: Ensures the C++ object is created

Use of this method is deprecated. Use _create instead

dbbox

Signature: [const] DBox dbbox

Description: Gets the bounding box of the cell in micrometer units

The bounding box is computed over all layers. To compute the bounding box over single layers, use dbbox_per_layer.

This method has been introduced in version 0.25.

dbbox_per_layer

Signature: [const] DBox dbbox_per_layer (unsigned int layer_index)

Description: Gets the per-layer bounding box of the cell in micrometer units

The bounding box is the box enclosing all shapes on the given layer.

This method has been introduced in version 0.25.

delete

Signature: void delete

Description: Deletes this cell

This deletes the cell but not the sub cells of the cell. These subcells will likely become new top cells unless they are used otherwise. All instances of this cell are deleted as well. Hint: to delete multiple cells, use "delete_cells" which is far more efficient in this case.

After the cell has been deleted, the Cell object becomes invalid. Do not access methods or attributes of this object after deleting the cell.

This method has been introduced in version 0.23.

delete_property

Signature: void delete_property (variant key)

Description: Deletes the user property with the given key

This method is a convenience method that deletes the property with the given key. It does nothing if no property with that key exists. Using that method is more convenient than creating a new property set with a new ID and assigning that properties ID. This method may change the properties ID.

This method has been introduced in version 0.23.

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

display_title

Signature: [const] string display_title

Description: Returns a nice looking name for display purposes

For example, this name include PCell parameters for PCell proxy cells.

This method has been introduced in version 0.22.

each_child_cell

Signature: [const,iter] unsigned int each_child_cell

Description: Iterates over all child cells

This iterator will report the child cell indices, not every instance.

each_inst

Signature: [iter] Instance each_inst

Description: Iterates over all child instances (which may actually be instance arrays)

Starting with version 0.15, this iterator delivers Instance objects rather than CellInstArray objects.

each_overlapping_inst

Signature: [const,iter] Instance each_overlapping_inst (const Box b)

Description: Gets the instances overlapping the given rectangle

This will iterate over all child cell instances overlapping with the given rectangle b.

Starting with version 0.15, this iterator delivers Instance objects rather than CellInstArray objects.

Signature: [const,iter] Instance each_overlapping_inst (const DBox b)

Description: Gets the instances overlapping the given rectangle, with the rectangle in micrometer units

This will iterate over all child cell instances overlapping with the given rectangle b. This method is identical to the each_overlapping_inst version that takes a Box object, but instead of taking database unit coordinates in will take a micrometer unit DBox object.

This variant has been introduced in version 0.25.

each_overlapping_shape

Signature: [const,iter] Shape each_overlapping_shape (unsigned int layer_index,const Box box,unsigned int flags)

Description: Iterates over all shapes of a given layer that overlap the given box

Signature: [const,iter] Shape each_overlapping_shape (unsigned int layer_index,const Box box)

Description: Iterates over all shapes of a given layer that overlap the given box

This call is equivalent to each_overlapping_shape(layer_index,box,RBA::Shapes::SAll). This convenience method has been introduced in version 0.16.

Signature: [const,iter] Shape each_overlapping_shape (unsigned int layer_index,const DBox box,unsigned int flags)

Description: Iterates over all shapes of a given layer that overlap the given box, with the box given in micrometer units

Signature: [const,iter] Shape each_overlapping_shape (unsigned int layer_index,const DBox box)

Description: Iterates over all shapes of a given layer that overlap the given box, with the box given in micrometer units

This call is equivalent to each_overlapping_shape(layer_index,box,RBA::Shapes::SAll). This convenience method has been introduced in version 0.16.

each_parent_cell

Signature: [const,iter] unsigned int each_parent_cell

Description: Iterates over all parent cells

This iterator will iterate over the parent cells, just returning their cell index.

each_parent_inst

Signature: [const,iter] ParentInstArray each_parent_inst

Description: Iterates over the parent instance list (which may actually be instance arrays)

The parent instances are basically inversions of the instances. Using parent instances it is possible to determine how a specific cell is called from where.

each_shape

Signature: [const,iter] Shape each_shape (unsigned int layer_index,unsigned int flags)

Description: Iterates over all shapes of a given layer

This iterator is equivalent to 'shapes(layer).each'.

Signature: [const,iter] Shape each_shape (unsigned int layer_index)

Description: Iterates over all shapes of a given layer

This call is equivalent to each_shape(layer_index,RBA::Shapes::SAll). This convenience method has been introduced in version 0.16.

each_touching_inst

Signature: [const,iter] Instance each_touching_inst (const Box b)

Description: Gets the instances touching the given rectangle

This will iterate over all child cell instances overlapping with the given rectangle b.

Starting with version 0.15, this iterator delivers Instance objects rather than CellInstArray objects.

Signature: [const,iter] Instance each_touching_inst (const DBox b)

Description: Gets the instances touching the given rectangle, with the rectangle in micrometer units

This will iterate over all child cell instances touching the given rectangle b. This method is identical to the each_touching_inst version that takes a Box object, but instead of taking database unit coordinates in will take a micrometer unit DBox object.

This variant has been introduced in version 0.25.

each_touching_shape

Signature: [const,iter] Shape each_touching_shape (unsigned int layer_index,const Box box,unsigned int flags)

Description: Iterates over all shapes of a given layer that touch the given box

Signature: [const,iter] Shape each_touching_shape (unsigned int layer_index,const Box box)

Description: Iterates over all shapes of a given layer that touch the given box

This call is equivalent to each_touching_shape(layer_index,box,RBA::Shapes::SAll). This convenience method has been introduced in version 0.16.

Signature: [const,iter] Shape each_touching_shape (unsigned int layer_index,const DBox box,unsigned int flags)

Description: Iterates over all shapes of a given layer that touch the given box, with the box given in micrometer units

Signature: [const,iter] Shape each_touching_shape (unsigned int layer_index,const DBox box)

Description: Iterates over all shapes of a given layer that touch the given box, with the box given in micrometer units

This call is equivalent to each_touching_shape(layer_index,box,RBA::Shapes::SAll). This convenience method has been introduced in version 0.16.

erase

Signature: void erase (const Instance inst)

Description: Erases the instance given by the Instance object

This method has been introduced in version 0.16. It can only be used in editable mode.

fill_region

Signature: void fill_region (const Region region,unsigned int fill_cell_index,const Box fc_box,const Point ptr origin)

Description: Fills the given region with cells of the given type

This method creates a regular pattern of fill cells to cover the interior of the given region as far as possible. This process is also known as tiling. The current implementation supports rectangular (not necessarily square) tile cells. The tile cell's footprint is given by the fc_box parameter and the cells will be arranged with their footprints forming a seamless array.

The algorithm supports a global fill raster as well as local (per-polygon) origin optimization. In the latter case the origin of the regular raster is optimized per individual polygon of the fill region.

A more elaborate version of this method is available which also returns informations about the non-filled parts.

This method has been introduced in version 0.23.

Signature: void fill_region (const Region region,unsigned int fill_cell_index,const Box fc_box,const Point ptr origin,Region ptr remaining_parts,const Vector fill_margin,Region ptr remaining_polygons)

Description: Fills the given region with cells of the given type (extended version)

First of all, this method behaves like the simple form. In addition, it can be configured to return information about the parts which could not be filled. Those can be full polygons from the input (without a chance to fill) or parts of original polygons which are worth being fed into the fill algorithm again.

If the 'remaining_parts' argument is non-nil, the corresponding region will receive the parts of the polygons which are not covered by tiles. Basically the tiles are subtracted from the original polygons. A margin can be specified which is applied separately in x and y direction before the subtraction is done ('fill_margin' parameter).

If the 'remaining_polygons' argument is non-nil, the corresponding region will receive all polygons from the input region which could not be filled and where there is no chance of filling because not a single tile will fit into them.

'remaining_parts' and 'remaining_polygons' can be identical with the input. In that case the input will be overwritten with the respective output. Otherwise, the respective polygons are added to these regions.

This allows to set up a more elaborate fill scheme using multiple iterations and local origin-optimization ('origin' is nil):

r = ...        # region to fill
c = ...        # cell in which to produce the fill cells
fc_index = ... # fill cell index
fc_box = ...   # fill cell footprint

fill_margin = RBA::Point::new(0, 0)   # x/y distance between tile cells with different origin

# Iteration: fill a region and fill the remaining parts as long as there is anything left.
# Polygons not worth being considered further are dropped (last argument is nil).
while !r.is_empty?
  c.fill_region(r, fc_index, fc_box, nil, r, fill_margin, nil)
end

This method has been introduced in version 0.23.

flatten

Signature: void flatten (bool prune)

Description: Flattens the given cell

This method propagates all shapes from the hierarchy below into the given cell. It also removes the instances of the cells from which the shapes came from, but does not remove the cells themselves if prune is set to false. If prune is set to true, these cells are removed if not used otherwise.

A version of this method exists which allows to specify the number of hierarchy levels to which subcells are considered.

This method has been introduced in version 0.23.

Signature: void flatten (int levels,bool prune)

Description: Flattens the given cell

This method propagates all shapes from the specified number of hierarchy levels below into the given cell. It also removes the instances of the cells from which the shapes came from, but does not remove the cells themselves if prune is set to false. If prune is set to true, these cells are removed if not used otherwise.

This method has been introduced in version 0.23.

ghost_cell=

Signature: void ghost_cell= (bool flag)

Description: Sets the "ghost cell" flag

See is_ghost_cell? for a description of this property.

This method has been introduced in version 0.20.

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

has_prop_id?

Signature: [const] bool has_prop_id?

Description: Returns true, if the cell has user properties

This method has been introduced in version 0.23.

hierarchy_levels

Signature: [const] unsigned int hierarchy_levels

Description: Returns the number of hierarchy levels below

This method returns the number of call levels below the current cell. If there are no child cells, this method will return 0, if there are only direct children, it will return 1.

CAUTION: this method may be expensive!

insert

Signature: Instance insert (const Instance inst)

Description: Inserts a cell instance given by another reference

This method allows to copy instances taken from a reference (an Instance object). This method is not suited to inserting instances from other Layouts into this cell. For this purpose, the hierarchical copy methods of Layout have to be used.

It has been added in version 0.16.

Signature: Instance insert (const CellInstArray cell_inst_array)

Description: Inserts a cell instance (array)

With version 0.16, this method returns an Instance object that represents the new instance. It's use is discouraged in readonly mode, since it invalidates other Instance references.

Signature: Instance insert (const DCellInstArray cell_inst_array)

Description: Inserts a cell instance (array) given in micron units

This method inserts an instance array, similar to insert with a CellInstArray parameter. But in this version, the argument is a cell instance array given in micrometer units. It is translated to database units internally.

This variant has been introduced in version 0.25.

Signature: Instance insert (const DCellInstArray cell_inst_array,unsigned long property_id)

Description: Inserts a cell instance (array) given in micron units with properties

This method inserts an instance array, similar to insert with a CellInstArray parameter and a property set ID. But in this version, the argument is a cell instance array given in micrometer units. It is translated to database units internally.

This variant has been introduced in version 0.25.

Signature: Instance insert (const CellInstArray cell_inst_array,unsigned long property_id)

Description: Inserts a cell instance (array) with properties

The property Id must be obtained from the Layout object's property_id method which associates a property set with a property Id. With version 0.16, this method returns an Instance object that represents the new instance. It's use is discouraged in readonly mode, since it invalidates other Instance references.

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

is_empty?

Signature: [const] bool is_empty?

Description: Returns a value indicating whether the cell is empty

An empty cell is a cell not containing instances nor any shapes.

This method has been introduced in version 0.20.

is_ghost_cell?

Signature: [const] bool is_ghost_cell?

Description: Returns a value indicating whether the cell is a "ghost cell"

The ghost cell flag is used by the GDS reader for example to indicate that the cell is not located inside the file. Upon writing the reader can determine whether to write the cell or not. To satisfy the references inside the layout, a dummy cell is created in this case which has the "ghost cell" flag set to true.

This method has been introduced in version 0.20.

is_leaf?

Signature: [const] bool is_leaf?

Description: Gets a value indicating whether the cell is a leaf cell

A cell is a leaf cell if there are no child instantiations.

is_library_cell?

Signature: [const] bool is_library_cell?

Description: Returns true, if the cell is a proxy cell pointing to a library cell

If the cell is imported from some library, this attribute returns true. Please note, that this attribute can combine with is_pcell? for PCells imported from a library.

This method has been introduced in version 0.22.

is_pcell_variant?

Signature: [const] bool is_pcell_variant?

Description: Returns true, if this cell is a pcell variant

this method returns true, if this cell represents a pcell with a distinct set of parameters (a PCell proxy). This also is true, if the PCell is imported from a library.

Technically, PCell's imported from a library are library proxies which are pointing to PCell variant proxies. This scheme can even proceed over multiple indirections, i.e. a library using PCell's from another library.

This method has been introduced in version 0.22.

Signature: [const] bool is_pcell_variant? (const Instance instance)

Description: Returns true, if this instance is a PCell variant

This method returns true, if this instance represents a PCell with a distinct set of parameters. This method also returns true, if it is a PCell imported from a library.

This method has been introduced in version 0.22.

is_proxy?

Signature: [const] bool is_proxy?

Description: Returns true, if the cell presents some external entity

A cell may represent some data which is imported from some other source, i.e. a library. Such cells are called "proxy cells". For a library reference, the proxy cell is some kind of pointer to the library and the cell within the library.

For PCells, this data can even be computed through some script. A PCell proxy represents all instances with a given set of parameters.

Proxy cells cannot be modified, except that pcell parameters can be modified and PCell instances can be recomputed.

This method has been introduced in version 0.22.

is_top?

Signature: [const] bool is_top?

Description: Gets a value indicating whether the cell is a top-level cell

A cell is a top-level cell if there are no parent instantiations.

is_valid?

Signature: [const] bool is_valid? (const Instance instance)

Description: Tests if the given Instance object is still pointing to a valid object

This method has been introduced in version 0.16. If the instance represented by the given reference has been deleted, this method returns false. If however, another instance has been inserted already that occupies the original instances position, this method will return true again.

layout

Signature: Layout ptr layout

Description: Returns a reference to the layout where the cell resides

this method has been introduced in version 0.22.

Signature: [const] const Layout ptr layout

Description: Returns a reference to the layout where the cell resides (const references)

this method has been introduced in version 0.22.

library

Signature: [const] Library ptr library

Description: Returns a reference to the library from which the cell is imported

if the cell is not imported from a library, this reference is nil.

this method has been introduced in version 0.22.

library_cell_index

Signature: [const] unsigned int library_cell_index

Description: Returns the index of the cell in the layout of the library (if it's a library proxy)

Together with the library method, it is possible to locate the source cell of a library proxy. The source cell can be retrieved from a cell "c" with

c.library.layout.cell(c.library_cell_index)

This cell may be itself a proxy, i.e. for pcell libraries, where the library cells are pcell variants which itself are proxies to a pcell.

This method has been introduced in version 0.22.

move

Signature: void move (unsigned int src,unsigned int dest)

Description: Moves the shapes from the source to the target layer

The destination layer is not overwritten. Instead, the shapes are added to the shapes of the destination layer. This method will move shapes within the cell. To move shapes from another cell this cell, use the copy method with the cell parameter.

This method has been introduced in version 0.19.

Signature: void move (Cell ptr src_cell,unsigned int src_layer,unsigned int dest)

Description: Moves shapes from another cell to the target layern this cell

This method will move all shapes on layer 'src_layer' of cell 'src_cell' to the layer 'dest' of this cell. The destination layer is not overwritten. Instead, the shapes are added to the shapes of the destination layer. If the source cell lives in a layout with a different database unit than that current cell is in, the shapes will be transformed accordingly. The same way, shape properties are transformed as well. Note that the shape transformation may require rounding to smaller coordinates. This may result in a slight distortion of the original shapes, in particular when transforming into a layout with a bigger database unit.

move_instances

Signature: void move_instances (Cell source_cell)

Description: Moves the instances of child cells in the source cell to this cell

The source cell must reside in the same layout than this cell. The instances of child cells inside the source cell are moved to this cell. No new cells are created, just new instances are created to already existing cells in the target cell.

The instances will be added to any existing instances in the cell.

More elaborate methods of moving hierarchy trees between layouts are provided through the move_tree_shapes (in cooperation with the CellMapping class) or move_tree methods.

This method has been added in version 0.23.

move_shapes

Signature: void move_shapes (Cell source_cell)

Description: Moves the shapes from the given cell into this cell

All shapes are moved from the source cell to this cell. Instances are not moved.

The source cell can reside in a different layout. In this case, the shapes are moved over from the other layout into this layout. Database unit conversion is done automatically if the database units differ between the layouts. Note that this may lead to grid snapping effects if the database unit of the target layout is not an integer fraction of the source layout.

If source and target layout are different, the layers of the source and target layout are identified by their layer/datatype number or name (if no layer/datatype is present). The shapes will be added to any shapes already in the cell.

This method has been added in version 0.23.

Signature: void move_shapes (Cell source_cell,const LayerMapping layer_mapping)

Description: Moves the shapes from the given cell into this cell

All shapes on layers specified in the layer mapping object are moved from the source cell to this cell. Instances are not moved. The target layer is taken from the mapping table.

The shapes will be added to any shapes already in the cell.

This method has been added in version 0.23.

move_tree

Signature: unsigned int[] move_tree (Cell source_cell)

Description: Moves the cell tree of the given cell into this cell

The complete cell tree of the source cell is moved to the target cell plus all shapes in that tree are moved as well. This method will basically rebuild the cell tree of the source cell and empty the source cell.

The source cell may reside in a separate layout. This method therefore provides a way to move over complete cell trees from one layout to another.

The shapes and instances will be added to any shapes or instances already in the cell.

This method has been added in version 0.23.

move_tree_shapes

Signature: void move_tree_shapes (Cell source_cell,const CellMapping cell_mapping)

Description: Moves the shapes from the given cell and the cell tree below into this cell or subcells of this cell

This method is provided if source and target cell reside in different layouts. If will move the shapes from all cells below the given source cell, but use a cell mapping object that provides a specification how cells are identified between the layouts. Cells in the source tree, for which no mapping is provided, will be flattened - their shapes will be propagated into parent cells for which a mapping is provided.

The cell mapping object provides various methods to map cell trees between layouts. See the CellMapping class for details about the mapping methods available. The cell mapping object is also responsible for creating a proper hierarchy of cells in the target layout if that is required.

Layers are identified between the layouts by the layer/datatype number of name if no layer/datatype number is present.

The shapes moved will be added to any shapes already in the cells.

This method has been added in version 0.23.

Signature: void move_tree_shapes (Cell source_cell,const CellMapping cell_mapping,const LayerMapping layer_mapping)

Description: Moves the shapes from the given cell and the cell tree below into this cell or subcells of this cell with layer mapping

This method is provided if source and target cell reside in different layouts. If will move the shapes from all cells below the given source cell, but use a cell mapping object that provides a specification how cells are identified between the layouts. Cells in the source tree, for which no mapping is provided, will be flattened - their shapes will be propagated into parent cells for which a mapping is provided.

The cell mapping object provides various methods to map cell trees between layouts. See the CellMapping class for details about the mapping methods available. The cell mapping object is also responsible for creating a proper hierarchy of cells in the target layout if that is required.

In addition, the layer mapping object can be specified which maps source to target layers. This feature can be used to restrict the move operation to a subset of layers or to convert shapes to different layers in that step.

The shapes moved will be added to any shapes already in the cells.

This method has been added in version 0.23.

name

Signature: [const] string name

Description: Gets the cell's name

This method has been introduced in version 0.22.

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

name=

Signature: void name= (string name)

Description: Renames the cell

Renaming a cell may cause name clashes, i.e. the name may be identical to the name of another cell. This does not have any immediate effect, but the cell needs to be renamed, for example when writing the layout to a GDS file.

This method has been introduced in version 0.22.

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

new

Signature: [static] new Cell ptr new

Description: Creates a new object of this class

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

parent_cells

Signature: [const] unsigned long parent_cells

Description: Gets the number of parent cells

The number of parent cells (cells which reference our cell) is reported.

pcell_declaration

Signature: [const] const PCellDeclaration ptr pcell_declaration

Description: Returns a reference to the PCell declaration

If this cell is not a PCell variant, this method returns nil. PCell variants are proxy cells which are PCell incarnations for a specific parameter set. The PCellDeclaration object allows to retrieve PCell parameter definitions for example.

This method has been introduced in version 0.22.

Signature: [const] const PCellDeclaration ptr pcell_declaration (const Instance instance)

Description: Returns the PCell declaration of a pcell instance

If the instance is not a PCell instance, this method returns nil. The PCellDeclaration object allows to retrieve PCell parameter definitions for example.

This method has been introduced in version 0.22.

pcell_id

Signature: [const] unsigned long pcell_id

Description: Returns the PCell ID if the cell is a pcell variant

This method returns the ID which uniquely identifies the PCell within the layout where it's declared. It can be used to retrieve the PCell declaration or to create new PCell variants.

The method will be rarely used. It's more convenient to use pcell_declaration to directly retrieve the PCellDeclaration object for example.

This method has been introduced in version 0.22.

pcell_library

Signature: [const] Library ptr pcell_library

Description: Returns the library where the PCell is declared if this cell is a PCell and it is not defined locally.

A PCell often is not declared within the current layout but in some library. This method returns a reference to that library, which technically is the last of the chained library proxies. If this cell is not a PCell or it is not located in a library, this method returns nil.

This method has been introduced in version 0.22.

pcell_parameter

Signature: [const] variant pcell_parameter (string name)

Description: Gets a PCell parameter by name if the cell is a PCell variant

If the cell is a PCell variant, this method returns the parameter with the given name. If the cell is not a PCell variant or the name is not a valid PCell parameter name, the return value is nil.

This method has been introduced in version 0.25.

Signature: [const] variant pcell_parameter (const Instance instance,string name)

Description: Returns a PCell parameter by name for a pcell instance

If the given instance is a PCell instance, this method returns the value of the PCell parameter with the given name. If the instance is not a PCell instance or the name is not a valid PCell parameter name, this method returns nil.

This method has been introduced in version 0.25.

pcell_parameters

Signature: [const] variant[] pcell_parameters

Description: Returns the PCell parameters for a pcell variant

If the cell is a PCell variant, this method returns a list of values for the PCell parameters. If the cell is not a PCell variant, this method returns an empty list. This method also returns the PCell parameters if the cell is a PCell imported from a library.

This method has been introduced in version 0.22.

Signature: [const] variant[] pcell_parameters (const Instance instance)

Description: Returns the PCell parameters for a pcell instance

If the given instance is a PCell instance, this method returns a list of values for the PCell parameters. If the instance is not a PCell instance, this method returns an empty list.

This method has been introduced in version 0.22.

pcell_parameters_by_name

Signature: [const] map<string,variant> pcell_parameters_by_name

Description: Returns the PCell parameters for a pcell variant as a name to value dictionary

If the cell is a PCell variant, this method returns a dictionary of values for the PCell parameters with the parameter names as the keys. If the cell is not a PCell variant, this method returns an empty dictionary. This method also returns the PCell parameters if the cell is a PCell imported from a library.

This method has been introduced in version 0.24.

Signature: [const] map<string,variant> pcell_parameters_by_name (const Instance instance)

Description: Returns the PCell parameters for a pcell instance as a name to value dictionary

If the given instance is a PCell instance, this method returns a dictionary of values for the PCell parameters with the parameter names as the keys. If the instance is not a PCell instance, this method returns an empty dictionary.

This method has been introduced in version 0.24.

prop_id

Signature: [const] unsigned long prop_id

Description: Gets the properties ID associated with the cell

This method has been introduced in version 0.23.

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

prop_id=

Signature: void prop_id= (unsigned long id)

Description: Sets the properties ID associated with the cell

This method is provided, if a properties ID has been derived already. Usually it's more convenient to use delete_property, set_property or property.

This method has been introduced in version 0.23.

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

property

Signature: variant property (variant key)

Description: Gets the user property with the given key

This method is a convenience method that gets the property with the given key. If no property with that key exists, it will return nil. Using that method is more convenient than using the layout object and the properties ID to retrieve the property value. This method has been introduced in version 0.23.

prune_cell

Signature: void prune_cell

Description: Deletes the cell plus subcells not used otherwise

This deletes the cell and also all sub cells of the cell which are not used otherwise. All instances of this cell are deleted as well. A version of this method exists which allows to specify the number of hierarchy levels to which subcells are considered.

After the cell has been deleted, the Cell object becomes invalid. Do not access methods or attributes of this object after deleting the cell.

This method has been introduced in version 0.23.

Signature: void prune_cell (int levels)

Description: Deletes the cell plus subcells not used otherwise

This deletes the cell and also all sub cells of the cell which are not used otherwise. The number of hierarchy levels to consider can be specified as well. One level of hierarchy means that only the direct children of the cell are deleted with the cell itself. All instances of this cell are deleted as well.

After the cell has been deleted, the Cell object becomes invalid. Do not access methods or attributes of this object after deleting the cell.

This method has been introduced in version 0.23.

prune_subcells

Signature: void prune_subcells

Description: Deletes all sub cells of the cell which are not used otherwise

This deletes all sub cells of the cell which are not used otherwise. All instances of the deleted cells are deleted as well. A version of this method exists which allows to specify the number of hierarchy levels to which subcells are considered.

This method has been introduced in version 0.23.

Signature: void prune_subcells (int levels)

Description: Deletes all sub cells of the cell which are not used otherwise down to the specified level of hierarchy

This deletes all sub cells of the cell which are not used otherwise. All instances of the deleted cells are deleted as well. It is possible to specify how many levels of hierarchy below the given root cell are considered.

This method has been introduced in version 0.23.

qname

Signature: [const] string qname

Description: Returns the library-qualified name

Library cells will be indicated by returning a qualified name composed of the library name, a dot and the basic cell name. For example: "Basic.TEXT" will be the qname of the TEXT cell of the Basic library. For non-library cells, the qname is identical to the basic name (see name).

This method has been introduced in version 0.25.

refresh

Signature: void refresh

Description: Refreshes the cell

If the cell is a PCell or a proxy to a PCell in a library, this method recomputes the PCell. If the cell is a library proxy, this method reloads the information from the library, but not the library itself.

This method has been introduced in version 0.22.

replace

Signature: Instance replace (const Instance instance,const CellInstArray cell_inst_array)

Description: Replaces a cell instance (array) with a different one

This method has been introduced in version 0.16. It can only be used in editable mode. The instance given by the instance object (first argument) is replaced by the given instance (second argument). The new object will not have any properties.

Signature: Instance replace (const Instance instance,const CellInstArray cell_inst_array,unsigned long property_id)

Description: Replaces a cell instance (array) with a different one with properties

This method has been introduced in version 0.16. It can only be used in editable mode. The instance given by the instance object (first argument) is replaced by the given instance (second argument) with the given properties Id. The property Id must be obtained from the Layout object's property_id method which associates a property set with a property Id. The new object will not have any properties.

Signature: Instance replace (const Instance instance,const DCellInstArray cell_inst_array)

Description: Replaces a cell instance (array) with a different one, given in micrometer units

This method is identical to the corresponding replace variant with a CellInstArray argument. It however accepts a micrometer-unit DCellInstArray object which is translated to database units internally.

This variant has been introduced in version 0.25.

Signature: Instance replace (const Instance instance,const DCellInstArray cell_inst_array,unsigned long property_id)

Description: Replaces a cell instance (array) with a different one and new properties, where the cell instance is given in micrometer units

This method is identical to the corresponding replace variant with a CellInstArray argument and a property ID. It however accepts a micrometer-unit DCellInstArray object which is translated to database units internally.

This variant has been introduced in version 0.25.

replace_prop_id

Signature: Instance replace_prop_id (const Instance instance,unsigned long property_id)

Description: Replaces (or install) the properties of a cell

This method has been introduced in version 0.16. It can only be used in editable mode. Changes the properties Id of the given instance or install a properties Id on that instance if it does not have one yet. The property Id must be obtained from the Layout object's property_id method which associates a property set with a property Id.

set_property

Signature: void set_property (variant key,variant value)

Description: Sets the user property with the given key to the given value

This method is a convenience method that sets the property with the given key to the given value. If no property with that key exists, it will create one. Using that method is more convenient than creating a new property set with a new ID and assigning that properties ID. This method may change the properties ID. This method has been introduced in version 0.23.

shapes

Signature: Shapes shapes (unsigned int layer_index)

Description: Returns the shapes list of the given layer

This method allows to access the shapes list on a certain layer. If the layer does not exist yet, it is created.

swap

Signature: void swap (unsigned int layer_index1,unsigned int layer_index2)

Description: Swaps the layers given

This method swaps two layers inside this cell.

transform

Signature: Instance transform (const Instance instance,const Trans trans)

Description: Transforms the instance with the given transformation

This method has been introduced in version 0.16. The original instance may be deleted and re-inserted by this method. Therefore, a new reference is returned. It is permitted in editable mode only.

Signature: Instance transform (const Instance instance,const ICplxTrans trans)

Description: Transforms the instance with the given complex integer transformation

This method has been introduced in version 0.23. The original instance may be deleted and re-inserted by this method. Therefore, a new reference is returned. It is permitted in editable mode only.

Signature: Instance transform (const Instance instance,const DTrans trans)

Description: Transforms the instance with the transformation given in micrometer units

This method is identical to the corresponding transform method with a Trans argument. For this variant however, the transformation is given in micrometer units and is translated to database units internally.

This variant has been introduced in version 0.25.

Signature: Instance transform (const Instance instance,const DCplxTrans trans)

Description: Transforms the instance with the given complex floating-point transformation given in micrometer units

This method is identical to the corresponding transform method with a ICplxTrans argument. For this variant however, the transformation is given in micrometer units and is translated to database units internally.

This variant has been introduced in version 0.25.

transform_into

Signature: Instance transform_into (const Instance instance,const Trans trans)

Description: Transforms the instance into a new coordinate system with the given transformation

In contrast to the transform method, this method allows propagation of the transformation into child cells. More precisely: it applies just a part of the given transformation to the instance, such that when transforming the cell instantiated and it's shapes with the same transformation, the result will reflect the desired transformation. Mathematically spoken, the transformation of the instance (A) is transformed with the given transformation T using "A' = T * A * Tinv" where Tinv is the inverse of T. In effect, the transformation T commutes with the new instance transformation A' and can be applied to child cells as well. This method is therefore useful to transform a hierarchy of cells.

This method has been introduced in version 0.23. The original instance may be deleted and re-inserted by this method. Therefore, a new reference is returned. It is permitted in editable mode only.

Signature: Instance transform_into (const Instance instance,const ICplxTrans trans)

Description: Transforms the instance into a new coordinate system with the given complex integer transformation

See the comments for the simple-transformation version for a description of this method. This method has been introduced in version 0.23. The original instance may be deleted and re-inserted by this method. Therefore, a new reference is returned. It is permitted in editable mode only.

Signature: void transform_into (const Trans trans)

Description: Transforms the cell into a new coordinate system with the given transformation

This method transforms all instances and all shapes. The instances are transformed in a way that allows propagation of the transformation into child cells. For this, it applies just a part of the given transformation to the instance such that when transforming the shapes of the cell instantiated, the result will reflect the desired transformation. Mathematically spoken, the transformation of the instance (A) is transformed with the given transformation T using "A' = T * A * Tinv" where Tinv is the inverse of T. In effect, the transformation T commutes with the new instance transformation A' and can be applied to child cells as well. This method is therefore useful to transform a hierarchy of cells.

It has been introduced in version 0.23.

Signature: void transform_into (const ICplxTrans trans)

Description: Transforms the cell into a new coordinate system with the given complex integer transformation

See the comments for the simple-transformation version for a description of this method. This method has been introduced in version 0.23.

Signature: Instance transform_into (const Instance instance,const DTrans trans)

Description: Transforms the instance into a new coordinate system with the given transformation where the transformation is in micrometer units

This method is identical to the corresponding transform_into method with a Trans argument. For this variant however, the transformation is given in micrometer units and is translated to database units internally.

This variant has been introduced in version 0.25.

Signature: Instance transform_into (const Instance instance,const DCplxTrans trans)

Description: Transforms the instance into a new coordinate system with the given complex transformation where the transformation is in micrometer units

This method is identical to the corresponding transform_into method with a ICplxTrans argument. For this variant however, the transformation is given in micrometer units and is translated to database units internally.

This variant has been introduced in version 0.25.

Signature: void transform_into (const DTrans trans)

Description: Transforms the cell into a new coordinate system with the given transformation where the transformation is in micrometer units

This method is identical to the corresponding transform_into method with a Trans argument. For this variant however, the transformation is given in micrometer units and is translated to database units internally.

This variant has been introduced in version 0.25.

Signature: void transform_into (const DCplxTrans trans)

Description: Transforms the cell into a new coordinate system with the given complex integer transformation where the transformation is in micrometer units

This method is identical to the corresponding transform_into method with a ICplxTrans argument. For this variant however, the transformation is given in micrometer units and is translated to database units internally.

This variant has been introduced in version 0.25.

write

Signature: [const] void write (string file_name)

Description: Writes the cell to a layout file

The format of the file will be determined from the file name. Only the cell and it's subtree below will be saved.

This method has been introduced in version 0.23.

Signature: [const] void write (string file_name,const SaveLayoutOptions options)

Description: Writes the cell to a layout file

The format of the file will be determined from the file name. Only the cell and it's subtree below will be saved. In contrast to the other 'write' method, this version allows to specify save options, i.e. scaling etc.

This method has been introduced in version 0.23.