---
title: "API Reference"
description: "Complete reference for every class and function in the Rosette Python API."
canonical_url: "https://www.rosette.dev/docs/api-reference"
markdown_url: "https://www.rosette.dev/docs/api-reference.md"
source_url: "https://github.com/PreFab-Photonics/rosette/blob/f086d7670645fd36c05362d696d442a2b2e74850/www/content/docs/api-reference/index.mdx"
docs_channel: "main"
docs_revision: "f086d7670645fd36c05362d696d442a2b2e74850"
---

# API Reference

> **Warning: Unstable API**
>
> Rosette is pre-1.0. Function signatures, class interfaces, and behavior may change between releases without notice.



For machine-readable contracts, use the complete [Python API stub](/api.pyi)
and [CLI manifest](/cli.json). In an initialized project, prefer the generated
`.rosette/api.pyi` and `.rosette/cli.json` when `.rosette/manifest.json` matches
the installed package. If Rosette reports stale references, run
`uv run rosette update`. This website tracks current development.

```python
from rosette import Cell, Layer, Point, Polygon
from rosette.io import write_gds
from rosette.routing import BendInfo, Route

# Create a simple cell
cell = Cell("my_design")
cell.add_polygon(Polygon.rect(Point.origin(), 10, 5), Layer(1, 0))
write_gds("output.gds", cell)

# Route between ports
route = Route(Layer(1, 0), width=0.5, bend_radius=5.0)
route.start_at_port(port_a)
route.to(50, 0)
route.end_at_port(port_b)
cell = route.to_cell("my_route")
```

In user projects (after `rosette init`), components are local:

```python
from components import mmi, ring, grating_coupler
```

For library development, import from `rosette.components`:

```python
from rosette.components import mmi, ring, grating_coupler
```

The component surface is documented by project template rather than as a stable core
API. See the [generic component catalog](/docs/templates/generic/components) or the
[blank component scaffold](/docs/templates/blank/components). The shared
[component-authoring guide](/docs/templates/component-authoring) applies to both.
After initialization, the project-local `components/` source is authoritative.

## Classes

### Geometry



- [Point](/docs/api-reference/Point)





- [Vector2](/docs/api-reference/Vector2)





- [Polygon](/docs/api-reference/Polygon)





- [BBox](/docs/api-reference/BBox)





- [Transform](/docs/api-reference/Transform)



### Layout



- [Cell](/docs/api-reference/Cell)





- [Instance](/docs/api-reference/Instance)





- [ArrayCopy](/docs/api-reference/ArrayCopy)





- [Route](/docs/api-reference/Route)





- [BendInfo](/docs/api-reference/BendInfo)





- [Library](/docs/api-reference/Library)





- [Layer](/docs/api-reference/Layer)





- [Port](/docs/api-reference/Port)





- [PathCap](/docs/api-reference/PathCap)



### Component metrics

Component functions return geometry-only Cells. When a component has a
meaningful optical metric, import its semantically named companion from
`components` in a generated project or from `rosette.components` during
library development:

| Function                              | Metric                                                     |
| ------------------------------------- | ---------------------------------------------------------- |
| `sbend_path_length(...)`              | S-bend centerline length.                                  |
| `mmi_through_length(...)`             | Straight through length across the MMI and tapers.         |
| `ring_round_trip_length(...)`         | Ring or racetrack resonator round-trip length.             |
| `crossing_through_length(...)`        | Through length across either crossing axis.                |
| `directional_coupler_arm_length(...)` | Centerline length of either symmetric coupler arm.         |
| `bragg_grating_length(...)`           | Total grating length, including terminator and phase stub. |

These names identify the measured path. Do not assume every component has one
generic path or a `Cell.path_length` value.

### Configuration



- [LayerInfo](/docs/api-reference/LayerInfo)





- [LayerMap](/docs/api-reference/LayerMap)



### DRC



- [DrcPolicy](/docs/api-reference/DrcPolicy)





- [DrcRules](/docs/api-reference/DrcRules)





- [DrcViolation](/docs/api-reference/DrcViolation)





- [DrcResult](/docs/api-reference/DrcResult)



### Design Checks



- [ChecksConfig](/docs/api-reference/ChecksConfig)





- [CheckViolation](/docs/api-reference/CheckViolation)





- [ChecksResult](/docs/api-reference/ChecksResult)



### DFM



- [DfmConfig](/docs/api-reference/DfmConfig)





- [GaussianModel](/docs/api-reference/GaussianModel)





- [LayerMetrics](/docs/api-reference/LayerMetrics)





- [DfmViolation](/docs/api-reference/DfmViolation)





- [LayerPrediction](/docs/api-reference/LayerPrediction)





- [DfmResult](/docs/api-reference/DfmResult)



### Rendering



- [RenderResult](/docs/api-reference/RenderResult)



## Functions

### I/O

Import `read_gds` and `write_gds` from `rosette.io`.



### `read_gds`

```python
read_gds(path) -> Library
```

Read a GDS file and return a Library.

Rosette emits a `UserWarning` when the source contains records that its
format-neutral model cannot preserve, such as element properties, BOX, or NODE.
Re-exporting such a library omits those records.



> **Example**
>
> ```python
> lib = read_gds("input.gds")
> print("roots:", [cell.name for cell in lib.roots()])
> for cell in lib.cells():
>     print(cell.name)
> ```





- **`path`** (`str | Path`)

  Path to the GDS file.





**Returns:** `Library`

A Library containing all cells from the GDS file.





### `write_gds`

```python
write_gds(path, design, cells=None, *, quiet=False, verbose=False) -> None
```

Write a Cell or Library to a GDS file.

When writing a Cell built using Instance references (via `cell.at()`),
child cells are automatically collected. A build summary is printed
to stderr by default.

Output uses a 1 nm database grid. Export raises `ValueError` instead of
silently collapsing geometry that is not representable on that grid. Library
names and text must be ASCII without embedded NUL characters; structure names
use the GDS Release 6 alphabet and maximum length of 32 characters.



> **Example**
>
> ```python
> # Auto-collection (recommended):
> top = Cell("top")
> top.add_ref(gc_cell.at(0, 0))
> write_gds("output.gds", top)
>
> # Suppress output for batch processing:
> write_gds("output.gds", top, quiet=True)
> ```





- **`path`** (`str | Path`)

  Output file path.





- **`design`** (`Cell | Library`)

  Cell or Library to write.





- **`cells`** (`list[Cell] | None`, default `None`)

  Optional list of child cells. If `None` and design is a Cell,
  child cells are auto-collected from Instance references.





- **`quiet`** (`bool`, default `False`)

  If `True`, suppress the build summary.





- **`verbose`** (`bool`, default `False`)

  If `True`, print detailed build info including port positions.





**Returns:** `None`



### Placement

Import `connect_transform` from `rosette`.



### `connect_transform`

```python
connect_transform(component_port, target_port) -> Transform
```

Calculate the transform that aligns a component port with a target port,
with their directions facing each other.



> **Example**
>
> ```python
> child = Cell("child")
> child_port = Port("in", Point(0, 0), Vector2(-1, 0), width=0.5)
> target_port = Port("out", Point(10, 0), Vector2(1, 0), width=0.5)
> transform = connect_transform(child_port, target_port)
> instance = Instance(child, transform)
> ```





- **`component_port`** (`Port`)

  Port on the component being placed.





- **`target_port`** (`Port`)

  Port to connect to.





**Returns:** `Transform`

Transform that aligns the two ports.



### Configuration

Import `load_layer_map` from `rosette.project`.



### `load_layer_map`

```python
load_layer_map(config_path=None) -> LayerMap
```

Load layer definitions from `rosette.toml`.

Reads the `[layers]` section which maps semantic names to GDS layer
numbers with optional display properties (color, fill, opacity).



> **Example**
>
> ```python
> layers = load_layer_map()
> layers.silicon.layer   # Layer(1, 0)
> layers.silicon.color   # "#ff69b4"
> ```





- **`config_path`** (`str | Path | None`, default `None`)

  Optional explicit path to `rosette.toml`. If `None`, searches
  from current directory upward.





**Returns:** `LayerMap`

LayerMap with named layer access.



### DRC

Import `DrcPolicy`, `load_drc_rules`, and `run_drc` from `rosette.drc`.



### `load_drc_rules`

```python
load_drc_rules(config_path=None) -> DrcRules
```

Load DRC rules from `rosette.toml`.

Searches for `rosette.toml` in the current directory and parent directories.
Rules are defined per-layer in the `[drc.layers]` section (supporting
`min_width`, `min_spacing`, `min_area`, `angles`, `min_edge_length`,
`max_width`, `acute_angle`, `snap_to_grid`, `density`, `no_self_intersection`,
and `no_overlap`), and inter-layer rules in the `[[drc.rules]]` array. See the
[project configuration reference](/docs/guides/project-configuration#design-rule-checking)
for the complete schema.

An optional top-level `[drc].warning_margin` knob downgrades near-threshold
numeric violations to warnings (see [`DrcRules.warning_margin`](/docs/api-reference/DrcRules#warning_margin)).

Layer keys can use semantic names from the `[layers]` section (e.g.
`[drc.layers.silicon]`) or the traditional `"number/datatype"` format
(e.g. `[drc.layers."1/0"]`). Inter-layer rules also accept semantic names
for `layer1`, `layer2`, `inner`, and `outer` fields.



> **Example**
>
> ```python
> rules = load_drc_rules()
> result = run_drc(cell, rules)
> ```





- **`config_path`** (`str | Path | None`, default `None`)

  Optional explicit path to `rosette.toml`. If `None`, searches
  from current directory upward.





**Returns:** `DrcRules`

DrcRules built from the configuration.





### `run_drc`

```python
run_drc(cell, rules, library=None, *, policy=None) -> DrcResult
```

Run DRC on a cell.



> **Example**
>
> ```python
> from rosette import BBox, Point
> from rosette.drc import DrcPolicy, load_drc_rules, run_drc
>
> rules = load_drc_rules()
> policy = DrcPolicy()
> policy.skip_cell("trusted_pdk_cell")
> policy.waive_region("taper", BBox(Point(9, -1), Point(11, 1)))
>
> result = run_drc(cell, rules, policy=policy)
> if result.passed:
>     print("DRC passed!")
> else:
>     for v in result.violations:
>         print(f"  {v.message}")
> ```





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

  The cell to check.





- **`rules`** (`DrcRules`)

  DRC rules to apply.





- **`library`** (`Library | None`, default `None`)

  Library containing referenced cells (required if cell has refs).





- **`policy`** (`DrcPolicy | None`, default `None`)

  Optional explicit per-run cell skips and local waiver regions. DRC policy is
  separate from Cell geometry; see [`DrcPolicy`](/docs/api-reference/DrcPolicy).





**Returns:** `DrcResult`

DrcResult with violations and statistics.



### Design Checks

Import `load_checks_config` and `run_checks` from `rosette.checks`.



### `load_checks_config`

```python
load_checks_config(config_path=None) -> ChecksConfig
```

Load design checks config from `rosette.toml`.

Reads the `[checks]` section. If absent, returns a `ChecksConfig`
with sensible defaults.



> **Example**
>
> ```python
> config = load_checks_config()
> result = run_checks(cell, config)
> ```





- **`config_path`** (`str | Path | None`, default `None`)

  Optional explicit path to `rosette.toml`. If `None`, searches
  from current directory upward.





**Returns:** `ChecksConfig`

ChecksConfig built from the configuration.





### `run_checks`

```python
run_checks(cell, config=None, library=None) -> ChecksResult
```

Run design checks on a cell.

Runs all design checks: connectivity (unconnected ports, width/angle
mismatch) and bend radius (below minimum, auto-reduced). Ports on
the top-level cell are treated as external I/O and are not flagged
as unconnected.

When called with a Cell built using Instance references, child cells
are automatically collected into a Library for hierarchy resolution.
Bend-radius checks read route diagnostics retained privately alongside Cells
created by `Route.to_cell()`; they do not inspect generic Cell metadata.



> **Example**
>
> ```python
> config = ChecksConfig(min_bend_radius=5.0)
> result = run_checks(cell, config)
> if not result.passed:
>     for v in result.violations:
>         print(f"  {v.message}")
> ```





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

  The cell to check.





- **`config`** (`ChecksConfig | None`, default `None`)

  Checks configuration. Defaults to `ChecksConfig()`.





- **`library`** (`Library | None`, default `None`)

  Library containing referenced cells. If `None` and cell has Instance
  tracking, a Library is auto-built.





**Returns:** `ChecksResult`

ChecksResult with violations and statistics.



### DFM

Import `load_dfm_config` and `run_dfm` from `rosette.dfm`.



### `load_dfm_config`

```python
load_dfm_config(config_path=None) -> tuple[DfmConfig, GaussianModel, list[Layer]] | None
```

Load DFM configuration from `rosette.toml`.

Reads the `[dfm]` section which configures the virtual nanofabrication
prediction tool. Layer references in the `layers` list and `[dfm.layer.*]`
overrides accept semantic names from the `[layers]` section (e.g.
`"silicon"`) or the traditional `"number/datatype"` format (e.g. `"1/0"`).

Returns `None` when `rosette.toml` has no `[dfm]` section, so callers can
treat "DFM not configured" as a graceful skip (matching how `[drc]` and
`[checks]` degrade) rather than an error. Only genuinely invalid DFM
settings raise.



> **Example**
>
> ```python
> loaded = load_dfm_config()
> if loaded is not None:
>     config, model, layers = loaded
>     result = run_dfm(cell, layers=layers, model=model, config=config)
> ```





- **`config_path`** (`str | Path | None`, default `None`)

  Optional explicit path to `rosette.toml`. If `None`, searches
  from current directory upward.





**Returns:** `tuple[DfmConfig, GaussianModel, list[Layer]] | None`

Tuple of (config, model, layers) where layers is the configured non-empty list
of layers to predict, or `None` when `rosette.toml` has no `[dfm]` section.





### `run_dfm`

```python
run_dfm(cell, layers, model=None, config=None, library=None) -> DfmResult
```

Run DFM prediction on a cell.

Rasterizes each specified layer, applies the fabrication prediction model,
and extracts contour polygons representing the predicted fabricated geometry.



> **Example**
>
> ```python
> result = run_dfm(cell, layers=[Layer(1, 0)])
> for lp in result.layers:
>     print(f"  Layer {lp.layer}: {lp.input_polygon_count} -> {lp.predicted_polygon_count}")
> ```





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

  The cell to predict.





- **`layers`** (`list[Layer]`)

  Layers to process.





- **`model`** (`GaussianModel | None`, default `None`)

  The prediction model. Defaults to `GaussianModel(sigma=0.08)`.





- **`config`** (`DfmConfig | None`, default `None`)

  DFM configuration. Defaults to `DfmConfig()`.





- **`library`** (`Library | None`, default `None`)

  Library containing referenced cells (required if cell has refs).





**Returns:** `DfmResult`

DfmResult with per-layer predictions and statistics.



### Geometry Utilities

Import `arc_points` from `rosette.geometry`.



### `arc_points`

```python
arc_points(center, radius, start_angle, end_angle, num_points=64) -> list[Point]
```

Generate points along a circular arc.



- **`center`** (`Point`)

  Center point of the arc.





- **`radius`** (`float`)

  Radius of the arc.





- **`start_angle`** (`float`)

  Starting angle in degrees (0 = +X direction).





- **`end_angle`** (`float`)

  Ending angle in degrees.





- **`num_points`** (`int`, default `64`)

  Number of points to generate.





**Returns:** `list[Point]`

List of points along the arc.



### Rendering

Import `render_png` from `rosette.render`.



> **Warning: Experimental**
>
> The rendering API is evolving; the signature and `RenderResult` shape may change
> without notice.





### `render_png`

```python
render_png(design, *, bbox=None, cell=None, layers=None, width=1024, height=None, pad=0.1, bg='#1a1a1a', fill_alpha=178, palette=None) -> RenderResult
```

Render a [`Cell`](/docs/api-reference/Cell) or [`Library`](/docs/api-reference/Library) to a PNG image, returning a
[`RenderResult`](/docs/api-reference/RenderResult) with the image bytes and world↔pixel transform
metadata.



- **`design`** (`Cell | Library`)

  The Cell or Library to render.





- **`bbox`** (`BBox | None`, default `None`)

  Optional explicit world-space region (microns). If omitted, derived from `cell`
  or the full library extent.





- **`cell`** (`str | None`, default `None`)

  Render only the named cell instead of the selected/unique top or the full
  multi-root library.





- **`layers`** (`list[tuple[int, int]] | None`, default `None`)

  Restrict rendering to these `(layer, datatype)` pairs.





- **`width`** (`int`, default `1024`)

  Output width in pixels.





- **`height`** (`int | None`, default `None`)

  Output height in pixels. If `None`, derived from aspect ratio.





- **`pad`** (`float`, default `0.1`)

  Fractional padding around the target bbox (`0.1` = 10%).





- **`bg`** (`str`, default `'#1a1a1a'`)

  Background color as `#RRGGBB` or `#RRGGBBAA`.





- **`fill_alpha`** (`int`, default `178`)

  Alpha applied to layer fill colors (0-255). Default 178 (\~70%).





- **`palette`** (`dict[int, str] | None`, default `None`)

  Optional `{layer_number: hex_color}` overrides.





**Returns:** `RenderResult`

A [`RenderResult`](/docs/api-reference/RenderResult) with `png` (bytes), `view` (dict), and
`layers_rendered`.