Instances

For the reference documentation see CellInstArray Class Reference and DCellInstArray Class Reference.

For the Instance object reference see Instance Class Reference.

Instances (or “references”) correspond to AREF and SREF objects in GDS. Instances “place” another cell inside a cell. When looking at a layout, an instance appears as a copy of the instantiated cell. This copy can be shifted, rotated or mirrored. Instances are used to generate bigger cells from smaller components. A typical application is to place instances of logic gates to form functional blocks.

Instance objects describe such cell placements with the following attributes:

  • A reference to the cell placed. In KLayout this is a cell index.
  • The transformation to apply. This is a simple or complex transformation object (see Transformations).
  • Optionally a regular array specification. An instance with an array specification corresponds to an AREF element in GDS.

KLayout’s API uses two (actually three) classes to represent instances:

  • CellInstArray and DCellInstArray are the input objects. These are the objects inserted into a cell to create an instance.
  • Instance is the object by which you retrieve instances from the database. Instance objects are directly connected to instances in the database and manipulating them changes the instance inside the database.

Note: although the classes are called CellInstArray, the do not necessarily represent arrays. Single instances are also represented by CellInstArray objects.

Here is an example for creating instances:

import klayout.db as db

ly = db.Layout()

# Creates a cell called "F" with some polygon

f_cell = ly.create_cell("F")

poly = db.DPolygon([ 
  db.DPoint(0, 0), db.DPoint(0, 5), db.DPoint(4, 5), db.DPoint(4, 4),
  db.DPoint(1, 4), db.DPoint(1, 3), db.DPoint(3, 3), db.DPoint(3, 2),
  db.DPoint(1, 2), db.DPoint(1, 0)
])

l1 = ly.layer(1, 0)
f_cell.shapes(l1).insert(poly)

# Place this cell two times in a new cell TOP

top_cell = ly.create_cell("TOP")

# The first placement is a single instance
i1 = db.DCellInstArray(f_cell.cell_index(), db.DTrans.R90)
top_cell.insert(i1)

# The second placement is a 2x3 array instance
i2 = db.DCellInstArray(
  f_cell.cell_index(),                  # cell reference
  db.DTrans(db.DTrans.M90, 10.0, 5.0),  # basic transformation
  db.DVector(0, 6),                     # a
  db.DVector(5, 0),                     # b
  2,                                    # na
  3                                     # nb
)
top_cell.insert(i2)

ly.write("instances.gds")

Result

Download GDS file

Instances can use complex transformations which enables any-angle rotations and cell scaling. A mentioned earlier such instances may be deprecated however in some applications.

Array instances are made from two step vectors (a and b) and two array dimensions (na and nb). The array expands to na*nb instances with additional displacements

d = i * a + j * b

with

i = 0 .. na-1
j = 0 .. nb-1

Warning: other systems reading your layout files may require that a and b are orthogonal vectors and are oriented along the x and y axis respectively.

KLayout does not impose such a restriction and supports skew arrays as well.