Library
A container for multiple cells.
Libraries group cells together for GDS I/O. When using write_gds() with
a single Cell built using Instance placements (via cell.at()), child
cells are auto-collected, so you typically don't need to create a Library
manually.
Libraries are primarily useful when reading GDS files with read_gds() or
when you need explicit control over which cells are included.
# Reading: read_gds returns a Library
lib = read_gds("input.gds")
roots = lib.roots()
top = lib.top_cell() # Explicit selection or a unique root
if top is None and roots:
lib.set_top_cell(roots[0].name)
for cell in lib.cells():
print(cell.name)
# Writing: usually not needed (write_gds auto-collects)
write_gds("output.gds", top_cell) # Auto-collects child cellsAttributes
attributenamestrLibrary name.
Methods
func__init__(name) -> NoneCreate a new empty library.
paramnamestrLibrary name.
Returns
Nonefuncadd_cell(cell, *, on_duplicate="error") -> NoneAdd a cell to the library.
Duplicate behavior is explicit: "error" raises ValueError, while "keep"
retains the existing definition.
paramcellCellThe cell to add.
paramon_duplicateLiteral["error", "keep"]Policy to apply when the identity already exists.
Returns
Nonefuncadd_cell_recursive(cell, available_cells, *, on_duplicate="keep") -> NoneAdd a cell and all its referenced cells recursively.
This method automatically adds all cells that are referenced by the given cell, resolving the entire hierarchy. You must provide a list of all available cells that may be referenced. The complete reachable hierarchy is validated before insertion, so failures are atomic.
Missing references, cycles, duplicate candidate identities, invalid names,
and rejected existing definitions raise ValueError.
paramcellCellThe cell to add (typically the top-level cell).
paramavailable_cellslist[Cell]List of all cells that may be referenced.
paramon_duplicateLiteral["error", "keep"]Whether reachable definitions already installed in the library are rejected or retained.
Returns
Nonefunccell(name) -> Cell | NoneGet a cell by name, or None if not found.
paramnamestrCell name to look up.
Returns
Cell | Nonefunccells() -> list[Cell]Get all cells in the library.
Returns
list[Cell]funcroots() -> list[Cell]Get graph-derived root cells in deterministic library order. A root is a cell that no other cell references. Multi-root GDS files therefore return every independent root, while a closed reference cycle may have no roots.
Returns
list[Cell]funcset_top_cell(name) -> NoneSelect an existing cell as the explicit top entry cell. This can also select a subtree that is not a graph root.
paramnamestrName of the cell to select.
Returns
NoneRaises ValueError when the cell does not exist.
funcclear_top_cell() -> NoneClear the explicit selection and restore unique-root inference.
Returns
Nonefunctop_cell() -> Cell | NoneGet the explicitly selected top cell, or the sole graph-derived root when the
library is unambiguous. Returns None for empty, multi-root, and rootless
cyclic libraries without an explicit selection.
The versioned Rosette JSON format preserves explicit top selection. GDS has no top-cell record, so selection is not preserved across GDS round trips.
Returns
Cell | Nonefunccell_bbox(name) -> BBox | NoneCalculate the fully-resolved bounding box of a cell in this library.
Unlike Cell.bbox(), this recursively resolves every cell reference
(SREF and AREF) and expands array repetitions, so the returned box covers
everything that would appear when the cell is rendered or written to GDS.
lib = Library("design")
lib.add_cell(unit)
lib.add_cell(top) # contains a 5x3 AREF of `unit`
bb = lib.cell_bbox("top") # covers all 15 copiesparamnamestrName of the cell to measure.
Returns
BBox | NoneReturns None if the cell does not exist or contains no geometry.