Cell
A cell containing geometry, hierarchy, and ports.
Cells are the primary container for layout geometry. Each cell has a unique
name and holds polygons, paths, text labels, ports, and references to other
cells. Use cell.at(x, y) to create positioned instances for ergonomic
placement and port queries. Routing diagnostics and DRC policy are not Cell
metadata; they are owned by their respective feature APIs.
Python cell mutations validate their complete input before committing. Invalid
geometry, references, text, or ports raise ValueError and leave the cell
unchanged.
cell = Cell("my_design")
cell.add_polygon(Polygon.rect(Point.origin(), 10, 5), Layer(1, 0))
cell.add_port(Port("in", Point(0, 2.5), Vector2(-1, 0), width=0.5))
# Position and add to a parent cell
top = Cell("top")
top.add_ref(cell.at(100, 50))Attributes
attributenamestrCell name (unique within a design).
Methods
func__init__(name) -> NoneCreate a new empty cell.
paramnamestrName of the cell. Must be unique within a design, non-empty, at most 32 characters, and contain only printable ASCII (no spaces or Unicode).
Returns
NoneGeometry
funcadd_polygon(polygon, layer) -> NoneAdd a polygon to the cell.
parampolygonPolygonThe polygon to add.
paramlayerLayer | int | tuple[int, int]Target layer. Accepts a Layer object, a single int (datatype defaults to 0),
or a (number, datatype) tuple.
Returns
Nonefuncadd_path(points, width, layer, cap=None) -> NoneAdd a path (centerline with width) to the cell.
Paths are an alternative to polygons for representing waveguides and similar structures. They store a centerline and width, which can be more compact than storing the full polygon outline.
Example
cell = Cell("waveguide")
cell.add_path(
[Point(0, 0), Point(100, 0), Point(100, 50)],
width=0.5,
layer=1,
cap=PathCap.ROUND
)parampointslist[Point]At least two finite Point objects along the path centerline.
paramwidthfloatFinite, nonzero width of the path. Negative widths are absolute: they are not scaled with a reference magnification.
paramlayerLayer | int | tuple[int, int]Target layer.
paramcapPathCap | None= NonePath endpoint geometry. Defaults to PathCap.FLUSH.
Returns
NoneRaises ValueError without modifying the cell if the centerline or width is
invalid.
funcadd_text(text, position, layer, height=1.0) -> NoneAdd a text label to the cell.
Text labels are useful for debugging and documentation but are typically not fabricated.
Example
cell.add_text("Input", Point(0, 5), layer=10)
cell.add_text("Big Label", Point(0, 10), layer=10, height=5.0)paramtextstrThe text string.
parampositionPointFinite position of the text.
paramlayerLayer | int | tuple[int, int]Target layer.
paramheightfloat= 1.0Positive finite text height in user units.
Returns
NoneRaises ValueError without modifying the cell if the position or height is
invalid.
Port operations
funcadd_port(port) -> NoneAdd a validated port to the cell. Port names must be unique within a cell.
paramportPortThe port to add.
Returns
NoneRaises ValueError without modifying the cell if the port is invalid or its
name is already present.
funcport(name) -> PortGet a port by name.
paramnamestrName of the port to retrieve.
Returns
PortThe port object.
funcports() -> list[Port]Get all ports defined on this cell.
Returns
list[Port]List of all ports.
Counts
funcpolygon_count() -> intNumber of polygons in the cell (not counting child cells).
Returns
intfuncpolygons() -> list[tuple[Polygon, Layer]]Get all polygons (and their layers) stored directly on this cell.
Does not descend into referenced cells; only returns polygons added via
add_polygon. Cell references and paths are excluded.
Returns
list[tuple[Polygon, Layer]]List of (polygon, layer) tuples, in insertion order.
funcpath_count() -> intNumber of paths in the cell.
Returns
intfunctext_count() -> intNumber of text labels in the cell.
Returns
intfuncref_count() -> intNumber of cell references.
Returns
intfunccell_ref_names() -> list[str]Get the sorted unique names of cells referenced directly by this cell.
Returns
list[str]Bounding box
funcbbox() -> BBox | NoneCalculate the bounding box of the geometry directly in this cell.
Includes polygons and paths. Does not resolve cell references. If this
cell contains SREFs or AREFs, their contribution is ignored.
Use Library.cell_bbox(name) for the fully
resolved bounding box of a cell inside a library.
Returns None if the cell has no direct geometry.
Returns
BBox | NonePlacement
funcat(x, y) -> InstanceCreate a positioned instance of this cell.
This is the public way to place cells in a design. The returned Instance
keeps the cell and transform together, allowing direct transformed-port
queries.
Example
from rosette.components import grating_coupler
gc_cell = grating_coupler(layer=layers.silicon.layer)
gc_in = gc_cell.at(0, 0)
gc_out = gc_cell.at(0, 127)
# Get ports directly from instances
port_in = gc_in.port("opt")
port_out = gc_out.port("opt")paramxfloatFinite X coordinate.
paramyfloatFinite Y coordinate.
Returns
InstanceAn Instance positioned at (x, y).
funcadd_ref(ref) -> NoneAdd a resolved instance to this cell.
Use cell.at(x, y) to create the required Instance, including explicit
cell.at(0, 0) placement at the origin. The child cell is automatically
tracked so that write_gds() can collect the full hierarchy without a manual
cell list.
The reference transform must be finite, invertible, and representable as a GDS placement (translation, rotation, reflection, and uniform nonzero scale). Validation happens before the parent reference list or tracked child set is updated.
Example
top.add_ref(gc_cell.at(0, 0)) # Instance at position
top.add_ref(route.to_cell("wg").at(0, 0))paramrefInstanceA resolved Instance to place with its transform.
Returns
NoneRaises TypeError when ref is not an Instance, or ValueError when the
placement is invalid, without modifying the parent.