KLayout Manual: Main Index » Class Index » API reference - Class Cell

API reference - Class Cell

Description: The cell object

Public methods
Detailed description

A cell object consists of a set of shape containers (called layers), a set of child cell instances and auxiliary informations such as the parent instance list. A cell is identified through an index given to the cell upon instantiation. Cell instances refer to single instances or array instances. Both are encapsulated in the same object, the CellInstArray object. In the simple case, this object refers to a single instance. In the general case, this object may refer to a regular array of cell instances as well.

Starting from version 0.16, the child_inst and erase_inst methods are no longer available since they were using index addressing which is no longer supported. Instead, instances are now addressed with the Instance reference objects.

Public methods

[const]	string	basic_name		Returns the name of the library or PCell or the real name of the cell
[const]	Box	bbox		Retrieve the bounding box of the cell
[const]	Box	bbox_per_layer	(unsigned int layer_index)	Retrieve the per-layer bounding box of the cell
[const]	unsigned int[]	called_cells		Return a list of all called cells
[const]	unsigned int[]	caller_cells		Return a list of all caller cells
[const]	unsigned int	cell_index		The cell index accessor method
	Instance	change_pcell_parameters	(const Instance instance, variant[] parameters)	Changes the parameters for an individual PCell instance
[const]	unsigned int	child_cells		Report the number of child cells
[const]	unsigned int	child_instances		Number of child instances
	void	clear	(unsigned int layer_index)	Clear the shapes on the given layer
	void	clear_insts		Clear the instance list
	void	clear_shapes		Clear all shapes in the cell
	void	copy	(unsigned int src, unsigned int dest)	Copy the shapes from the source to the target layer
	void	create		Ensures the C++ object is created
	void	destroy		Explicitly destroy the object
[const]	bool	destroyed?		Returns a value indicating whether the object was already destroyed
[const]	string	display_title
[iter]	unsigned int	each_child_cell		Iterate over all child cells
[iter]	Instance	each_inst		Iterate over all child instances (which may actually be instance arrays)
[iter]	Instance	each_overlapping_inst	(const Box b)	Region query for the instances in "overlapping" mode
[const,iter]	Shape	each_overlapping_shape	(unsigned int layer_index, const Box box, unsigned int flags)	Iterate all shapes of a given layer that overlap the given box
[const,iter]	Shape	each_overlapping_shape	(unsigned int layer_index, const Box box)	Iterate all shapes of a given layer that overlap the given box
[const,iter]	unsigned int	each_parent_cell		Iterate over all parent cells
[iter]	ParentInstArray	each_parent_inst		Iterate over the parent instance list (which may actually be instance arrays)
[const,iter]	Shape	each_shape	(unsigned int layer_index, unsigned int flags)	Iterate all shapes of a given layer
[const,iter]	Shape	each_shape	(unsigned int layer_index)	Iterate all shapes of a given layer
[iter]	Instance	each_touching_inst	(const Box b)	Region query for the instances in "touching" mode
[const,iter]	Shape	each_touching_shape	(unsigned int layer_index, const Box box, unsigned int flags)	Iterate all shapes of a given layer that touch the given box
[const,iter]	Shape	each_touching_shape	(unsigned int layer_index, const Box box)	Iterate all shapes of a given layer that touch the given box
	void	erase	(const Instance inst)	Erase the instance given by the Instance object
	void	ghost_cell=	(bool flag)	Sets the "ghost cell" flag
[const]	unsigned int	hierarchy_levels		Return the number of hierarchy levels below (expensive)
	Instance	insert	(const Instance inst)	Insert a cell instance given by another reference
	Instance	insert	(const CellInstArray cell_inst_array)	Insert a cell instance (array)
	Instance	insert	(const CellInstArray cell_inst_array, unsigned int property_id)	Insert a cell instance (array) with properties
[const]	bool	is_const_object?		Returns a value indicating whether the reference is a const reference
[const]	bool	is_empty?		Returns a value indicating whether the cell is empty
[const]	bool	is_ghost_cell?		Returns a value indicating whether the cell is a "ghost cell"
[const]	bool	is_leaf?		Tell if the cell is a leaf cell
[const]	bool	is_library_cell?		Returns true, if the cell is a proxy cell pointing to a library cell
[const]	bool	is_pcell_variant?		returns true, if this cell is a pcell variant
[const]	bool	is_pcell_variant?	(const Instance instance)	Returns true, if this instance is a PCell variant
[const]	bool	is_proxy?		Returns true, if the cell presents some external entity
[const]	bool	is_top?		Tell if the cell is a top-level cell
[const]	bool	is_valid?	(const Instance instance)	Test if the given Instance object is still pointing to a valid object
	Layout ptr	layout		returns a reference to the layout where the cell resides
[const]	const Layout ptr	layout		returns a reference to the layout where the cell resides (const references)
[const]	Library ptr	library		returns a reference to the library from which the cell is imported
[const]	unsigned int	library_cell_index		Returns the index of the cell in the layout of the library (if it's a library proxy)
	void	move	(unsigned int src, unsigned int dest)	Move the shapes from the source to the target layer
[const]	string	name		Gets the cell's name
	void	name=	(string name)	Renames the cell
[const]	unsigned int	parent_cells		Report the number of parent cells
[const]	const PCellDeclaration ptr	pcell_declaration		Returns a reference to the PCell declaration
[const]	const PCellDeclaration ptr	pcell_declaration	(const Instance instance)	Returns the PCell declaration of a pcell instance
[const]	unsigned int	pcell_id		Returns the PCell ID if the cell is a pcell variant
[const]	Library ptr	pcell_library		Returns the library where the PCell is declared if this cell is a PCell and it is not defined locally.
[const]	variant[]	pcell_parameters		returns the PCell parameters for a pcell variant
[const]	variant[]	pcell_parameters	(const Instance instance)	returns the PCell parameters for a pcell instance
	void	refresh
	Instance	replace	(const Instance instance, const CellInstArray cell_inst_array)	Replace a cell instance (array) with a different one
	Instance	replace	(const Instance instance, const CellInstArray cell_inst_array, unsigned int property_id)	Replace a cell instance (array) with a different one with properties
	Instance	replace_prop_id	(const Instance instance, unsigned int property_id)	Replace (or install) the properties of a cell
	Shapes	shapes	(unsigned int layer_index)	Return the shapes list of the given layer
	void	swap	(unsigned int layer_index1, unsigned int layer_index2)	Swap the layers given
	Instance	transform	(const Instance instance, const Trans trans)	Transform the instance given by the instance with the given transformation
	Instance	transform	(const Instance instance, const CplxTrans trans)	Transform the instance given by the instance with the given complex transformation

Detailed description

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

[const] Box bbox

Description: Retrieve the bounding box of the cell

Returns:

The bounding box of the cell

[const] Box bbox_per_layer(unsigned int layer_index)

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

Returns:

The bounding box of the cell considering only the given layer

[const] unsigned int[] called_cells

Description: Return a list of all called cells

Returns:

A list of cell indices.

This method determines all cells which are called either directly or indirectly by the cell.

This method has been introduced in version 0.19.

[const] unsigned int[] caller_cells

Description: Return a list of all caller cells

Returns:

A list of cell indices.

This method determines all cells which call this cell either directly or indirectly.

This method has been introduced in version 0.19.

[const] unsigned int cell_index

Description: The cell index accessor method

Returns:

The cell index of the cell

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.

This method has been introduced in version 0.22.

[const] unsigned int child_cells

Description: Report the number of child cells

The number of child cells (not child instances!) is reported. CAUTION: this method is SLOW!

[const] unsigned int child_instances

Description: Number of child instances

Returns:

Returns the number of cell instances

void clear(unsigned int layer_index)

Description: Clear the shapes on the given layer

void clear_insts

Description: Clear the instance list

void clear_shapes

Description: Clear all shapes in the cell

void copy(unsigned int src,unsigned int dest)

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

src:	The layer index of the source layer
dest:	The layer index of the destination layer

The target layer is not overwritten. Instead, the shapes are added to the shapes of the target layer. If source are target layer are identical, this method does nothing.

This method has been introduced in version 0.19.

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.

void destroy

Description: Explicitly destroy the object

Explicitly destroy the object on C++ side if it was owned by the Ruby interpreter. Subsequent access to this object will throw an exception. If the object is not owned by Ruby, this method will do nothing.

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

[const] string display_title

Description:

@Returns Returns a nice looking name for display purposes

This method has been introduced in version 0.22.

[iter] unsigned int each_child_cell

Description: Iterate over all child cells

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

[iter] Instance each_inst

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

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

[iter] Instance each_overlapping_inst(const Box b)

Description: Region query for the instances in "overlapping" mode

b:	The region to query

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

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

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

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

flags:	An "or"-ed combination of the S.. constants of the Shapes class
box:	The box by which to query the shapes
layer_index:	The layer on which to run the query

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

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

box:	The box by which to query the shapes
layer_index:	The layer on which to run the query

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

[const,iter] unsigned int each_parent_cell

Description: Iterate over all parent cells

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

[iter] ParentInstArray each_parent_inst

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

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

Description: Iterate all shapes of a given layer

flags:	An "or"-ed combination of the S.. constants of the Shapes class
layer_index:	The layer on which to run the query

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

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

Description: Iterate all shapes of a given layer

layer_index:

The layer on which to run the query

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

[iter] Instance each_touching_inst(const Box b)

Description: Region query for the instances in "touching" mode

b:	The region to query

This will iterate over all child cell instances touching the given region b.

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

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

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

flags:	An "or"-ed combination of the S.. constants of the Shapes class
box:	The box by which to query the shapes
layer_index:	The layer on which to run the query

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

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

box:	The box by which to query the shapes
layer_index:	The layer on which to run the query

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

void erase(const Instance inst)

Description: Erase the instance given by the Instance object

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

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.

[const] unsigned int hierarchy_levels

Description: Return the number of hierarchy levels below (expensive)

Instance insert(const Instance inst)

Description: Insert a cell instance given by another reference

Returns:

An Instance object representing the new instance

This method allows to copy instances taken from a reference (an Instance object). It has been added in version 0.16.

Instance insert(const CellInstArray cell_inst_array)

Description: Insert a cell instance (array)

Returns:

An Instance object representing the new instance

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.

Instance insert(const CellInstArray cell_inst_array,unsigned int property_id)

Description: Insert a cell instance (array) with properties

Returns:

An Instance object representing the new instance

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.

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

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

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

[const] bool is_leaf?

Description: Tell if the cell is a leaf cell

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

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

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

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

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

[const] bool is_top?

Description: Tell if the cell is a top-level cell

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

[const] bool is_valid?(const Instance instance)

Description: Test 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 ptr layout

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

this method has been introduced in version 0.22.

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

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

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

void move(unsigned int src,unsigned int dest)

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

src:	The layer index of the source layer
dest:	The layer index of the destination layer

The target layer is not overwritten. Instead, the shapes are added to the shapes of the target layer.

This method has been introduced in version 0.19.

[const] string name

Description: Gets the cell's name

This method has been introduced in version 0.22.

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 method has been introduced in version 0.22.

[const] unsigned int parent_cells

Description: Report the number of parent cells

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

[const] const PCellDeclaration ptr pcell_declaration

Description: Returns a reference to the PCell declaration

If this cell is not a PCell, this method returns nil.

This method has been introduced in version 0.22.

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

This method has been introduced in version 0.22.

[const] unsigned int 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.

This method has been introduced in version 0.22.

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

[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 self 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.

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

void refresh

Description:

@Returns 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.

Instance replace(const Instance instance,const CellInstArray cell_inst_array)

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

Returns:

An Instance object representing the new instance

Instance replace(const Instance instance,const CellInstArray cell_inst_array,unsigned int property_id)

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

Returns:

An Instance object representing the new instance

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.

Instance replace_prop_id(const Instance instance,unsigned int property_id)

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

Returns:

An Instance object representing the new instance

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.

Shapes shapes(unsigned int layer_index)

Description: Return the shapes list of the given layer

index:	The layer index of the shapes list to retrieve
Returns:	A reference to the shapes list

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

void swap(unsigned int layer_index1,unsigned int layer_index2)

Description: Swap the layers given

Instance transform(const Instance instance,const Trans trans)

Description: Transform the instance given by the instance with the given transformation

Returns:

A reference (an Instance object) to the new instance

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.

Instance transform(const Instance instance,const CplxTrans trans)

Description: Transform the instance given by the instance with the given complex transformation

Returns:

A reference (an Instance object) to the new instance

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.