---
title: "Library"
description: "A container for multiple cells."
canonical_url: "https://www.rosette.dev/docs/api-reference/Library"
markdown_url: "https://www.rosette.dev/docs/api-reference/Library.md"
source_url: "https://github.com/PreFab-Photonics/rosette/blob/f086d7670645fd36c05362d696d442a2b2e74850/www/content/docs/api-reference/Library.mdx"
docs_channel: "main"
docs_revision: "f086d7670645fd36c05362d696d442a2b2e74850"
---

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

```python
# 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 cells
```

## Attributes



### `name`

```python
name: str
```

Library name.



## Methods



### `__init__`

```python
__init__(name) -> None
```

Create a new empty library.



- **`name`** (`str`)

  Library name.





**Returns:** `None`





### `add_cell`

```python
add_cell(cell, *, on_duplicate="error") -> None
```

Add a cell to the library.

Duplicate behavior is explicit: `"error"` raises `ValueError`, while `"keep"`
retains the existing definition.



- **`cell`** (`Cell`)

  The cell to add.





- **`on_duplicate`** (`Literal["error", "keep"]`, default `"error"`)

  Policy to apply when the identity already exists.





**Returns:** `None`





### `add_cell_recursive`

```python
add_cell_recursive(cell, available_cells, *, on_duplicate="keep") -> None
```

Add 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`.



- **`cell`** (`Cell`)

  The cell to add (typically the top-level cell).





- **`available_cells`** (`list[Cell]`)

  List of all cells that may be referenced.





- **`on_duplicate`** (`Literal["error", "keep"]`, default `"keep"`)

  Whether reachable definitions already installed in the library are rejected
  or retained.





**Returns:** `None`





### `cell`

```python
cell(name) -> Cell | None
```

Get a cell by name, or `None` if not found.



- **`name`** (`str`)

  Cell name to look up.





**Returns:** `Cell | None`





### `cells`

```python
cells() -> list[Cell]
```

Get all cells in the library.



**Returns:** `list[Cell]`





### `roots`

```python
roots() -> 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]`





### `set_top_cell`

```python
set_top_cell(name) -> None
```

Select an existing cell as the explicit top entry cell. This can also select a
subtree that is not a graph root.



- **`name`** (`str`)

  Name of the cell to select.





**Returns:** `None`



Raises `ValueError` when the cell does not exist.





### `clear_top_cell`

```python
clear_top_cell() -> None
```

Clear the explicit selection and restore unique-root inference.



**Returns:** `None`





### `top_cell`

```python
top_cell() -> Cell | None
```

Get 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 | None`





### `cell_bbox`

```python
cell_bbox(name) -> BBox | None
```

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

```python
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 copies
```



- **`name`** (`str`)

  Name of the cell to measure.





**Returns:** `BBox | None`



Returns `None` if the cell does not exist or contains no geometry.