Instance
A cell placed at a specific location with optional transformations.
Instance solves the ergonomic problem of needing to pass the Cell twice: once to create a CellRef, and again to query ports. With Instance, the Cell reference is preserved, allowing direct port queries.
# Old pattern (redundant):
gc_ref = CellRef(gc_cell).at(0, 0)
port = gc_ref.port("opt", gc_cell) # Must pass gc_cell again
# New pattern (ergonomic):
gc_in = gc_cell.at(0, 0) # Returns Instance
port = gc_in.port("opt") # No redundancy!Instances can be added directly to cells and support transform chaining:
gc = gc_cell.at(100, 50)
top.add_ref(gc)Transform chaining order
Each chained call wraps the outside of the accumulated transform. The first call in the chain is applied first to the geometry.
# .at(10, 0).rotate(90) -> translate first, THEN rotate around origin
# Point (0,0) becomes (10,0) then rotates to (0,10) -- NOT at (10,0)!
# To rotate a component then place it at a specific position,
# rotate first, then translate:
inst = cell.at(0, 0).rotate(90).at(25, 50) # rotate, then move to (25,50)Attributes
attributecellCellThe underlying cell definition.
attributetransformTransformThe current transform applied to this instance.
attributecell_namestrName of the referenced cell (for compatibility with CellRef).
attributearray_shapetuple[int, int]Grid dimensions (columns, rows) of this instance. Returns
(1, 1) for non-arrayed instances so the result is always
meaningful without checking whether array() was called.
Methods
func__init__(cell, transform=None) -> NoneCreate an Instance from a Cell and optional transform.
Typically you don't call this directly. Use cell.at(x, y) instead.
paramcellCellThe cell definition.
paramtransformTransform | None= NoneOptional transform. Defaults to identity.
Returns
Nonefuncat(x, y) -> InstanceSet the position (translation).
Returns a new Instance. Instances are immutable.
paramxfloatX coordinate.
paramyfloatY coordinate.
Returns
InstanceA new Instance with updated transform.
funcrotate(angle_deg) -> InstanceRotate by angle (in degrees, counter-clockwise).
paramangle_degfloatRotation angle in degrees.
Returns
InstanceA new Instance with updated transform.
funcmirror_x() -> InstanceMirror across X axis (flips Y coordinates).
Returns
InstanceA new Instance with updated transform.
funcmirror_y() -> InstanceMirror across Y axis (flips X coordinates).
Returns
InstanceA new Instance with updated transform.
funcscale(s) -> InstanceScale uniformly.
paramsfloatScale factor.
Returns
InstanceA new Instance with updated transform.
funcarray(columns, rows, col_spacing, row_spacing) -> InstanceSet array repetition (columns × rows rectangular grid with given pitch).
Creates a GDS AREF: a single compact array reference instead of many individual references. In the viewer, the entire array is selected and moved as one object.
For hex packings or any skewed / non-orthogonal grid, use
array_vectors instead.
Example
# 10×5 array with 20 µm column pitch and 15 µm row pitch
arr = unit_cell.at(0, 0).array(10, 5, 20.0, 15.0)
top.add_ref(arr)paramcolumnsintNumber of columns (>= 1).
paramrowsintNumber of rows (>= 1).
paramcol_spacingfloatColumn pitch: center-to-center distance between adjacent copies along local +X, in µm. Negative values place copies along local −X.
paramrow_spacingfloatRow pitch: center-to-center distance between adjacent copies along local +Y, in µm. Negative values place copies along local −Y.
Returns
InstanceA new Instance with array repetition set.
funcarray_vectors(columns, rows, col_vector, row_vector) -> InstanceSet array repetition from arbitrary column and row displacement vectors.
Lower-level constructor supporting non-orthogonal lattices: hex packings, skewed test arrays, etc. Vectors are defined in the instance's local (pre-transform) coordinate space, in µm.
Example
import math
from rosette import Vector2
# Hex packing (flat-top): adjacent rows staggered by pitch/2.
pitch = 10.0
arr = unit_cell.array_vectors(
6, 4,
Vector2(pitch, 0.0),
Vector2(pitch / 2.0, pitch * math.sqrt(3.0) / 2.0),
)
top.add_ref(arr)paramcolumnsintNumber of columns (1 to 32767).
paramrowsintNumber of rows (1 to 32767).
paramcol_vectorVector2Column displacement: the offset between copy (c, r) and
(c+1, r), in µm.
paramrow_vectorVector2Row displacement: the offset between copy (c, r) and
(c, r+1), in µm.
Returns
InstanceA new Instance with array repetition set.
funcport(name, col=0, row=0) -> PortGet a transformed port from this instance.
Unlike CellRef.port(), this doesn't require passing the Cell again
since the Instance already knows its cell definition. Both position
and direction are fully transformed (translation, rotation, mirroring).
For arrayed instances (see array / array_vectors), pass col
and row to address a specific copy in the lattice. The default
(0, 0) returns the port of the anchor copy, matching the
behaviour of non-arrayed instances.
Example
gc = gc_cell.at(100, 50)
opt_port = gc.port("opt") # Transformed port position & direction
# 180-degree rotation flips both position and direction:
flipped = gc_cell.at(0, 0).rotate(180).at(50, 0)
p = flipped.port("opt") # direction is now (-1, 0)
# Arrayed: address a specific copy.
bank = ring_cell.array(8, 1, 30.0, 0.0)
p = bank.port("in", col=3)paramnamestrName of the port to retrieve.
paramcolint= 0Grid column of the copy to query (0-indexed). Only meaningful on arrayed instances.
paramrowint= 0Grid row of the copy to query (0-indexed). Only meaningful on arrayed instances.
Returns
PortThe port with position and direction transformed into world space for the requested copy.
funccopies() -> Iterator[ArrayCopy]Iterate over the individual copies in this instance's array.
Yields one ArrayCopy per grid position, in
column-major order (col varies fastest). Each yielded object
exposes col, row, a world-space transform, and a port(name)
convenience, without mutating this instance or adding any extra
GDS references.
For a non-arrayed instance this yields exactly one copy at
(col=0, row=0), so code written against copies() works
uniformly regardless of whether array() was called.
Equivalent to iter(instance).
Example
bank = ring_cell.array(8, 1, 30.0, 0.0)
top.add_ref(bank) # one AREF
for copy in bank.copies():
top.add_text(
f"R{copy.col}",
copy.port("in").position,
layer=Layer(10, 0),
)Returns
Iterator[ArrayCopy]Iterator yielding one ArrayCopy per grid position.
functo_ref() -> CellRefConvert to a CellRef for use with low-level APIs.
The transform is decomposed into GDS-compatible components (mirror, rotation, translation) following the GDS convention.
Returns
CellRefA CellRef with the same cell name and transform.