---
title: "Port"
description: "A named port with position, direction, and optional width."
canonical_url: "https://www.rosette.dev/docs/api-reference/Port"
markdown_url: "https://www.rosette.dev/docs/api-reference/Port.md"
source_url: "https://github.com/PreFab-Photonics/rosette/blob/f086d7670645fd36c05362d696d442a2b2e74850/www/content/docs/api-reference/Port.mdx"
docs_channel: "main"
docs_revision: "f086d7670645fd36c05362d696d442a2b2e74850"
---

# Port

A named port with position, direction, and optional width.

Ports are the primary mechanism for connecting components and routing
waveguides. Each port has a position in layout space, a unit vector
`direction` pointing **outward** from the component, and an optional
`width` used for waveguide width matching.

Port names must be nonempty. Positions must be finite, directions must be
finite and nonzero, and optional widths must be positive and finite. Rosette
normalizes the direction during construction, so callers may pass any valid
nonzero vector. A cell cannot contain two ports with the same name. Invalid
Python inputs raise `ValueError` before changing model state.

```python
# Port facing +X at the origin, 0.5 um wide
p = Port("opt", Point(0, 0), Vector2(1, 0), width=0.5)

# Check the angle (degrees)
p.angle()  # 0.0

# Two ports can connect if they are co-located with opposite directions
other = Port("in", Point(0, 0), Vector2(-1, 0), width=0.5)
p.can_connect_to(other)  # True
```

## Attributes



### `name`

```python
name: str
```

Nonempty name of the port (e.g. `"opt"`, `"in"`, `"out_1"`). Names are
unique within a cell.





### `position`

```python
position: Point
```

Finite position of the port in layout coordinates.





### `direction`

```python
direction: Vector2
```

Normalized unit vector pointing **outward** from the component. For example,
a port on the right edge of a component has direction `(1, 0)`.





### `width`

```python
width: float | None
```

Positive finite waveguide width at this port, or `None` if unspecified.



## Methods



### `__init__`

```python
__init__(name, position, direction, width=None) -> None
```

Create a new Port.



> **Example**
>
> ```python
> Port("opt", Point(0, 0), Vector2(1, 0), width=0.5)
> Port("elec", Point(10, 5), Vector2(0, 1))  # No width
> ```





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

  Nonempty name of the port.





- **`position`** (`Point`)

  Finite position in layout coordinates.





- **`direction`** (`Vector2`)

  Finite, nonzero outward-facing vector. It is normalized during construction.





- **`width`** (`float | None`, default `None`)

  Positive finite waveguide width at the port, or `None`.





**Returns:** `None`



Raises `ValueError` if any invariant is violated.





### `angle`

```python
angle() -> float
```

Return the port direction as an angle in degrees.

The angle is measured counter-clockwise from the +X axis. For example,
a direction of `(1, 0)` returns `0.0`, and `(0, 1)` returns `90.0`.



**Returns:** `float`

Direction angle in degrees.





### `can_connect_to`

```python
can_connect_to(other, tolerance=0.001) -> bool
```

Check if this port can connect to another port.

Two ports can connect when they are at the same position (within
`tolerance`) and have opposite directions. This is the geometric
condition for a flush waveguide junction.



> **Example**
>
> ```python
> a = Port("out", Point(100, 0), Vector2(1, 0), width=0.5)
> b = Port("in", Point(100, 0), Vector2(-1, 0), width=0.5)
> a.can_connect_to(b)  # True: same position, opposite directions
>
> c = Port("in", Point(100, 1), Vector2(-1, 0), width=0.5)
> a.can_connect_to(c)  # False: positions differ
> ```





- **`other`** (`Port`)

  The other port to check against.





- **`tolerance`** (`float`, default `0.001`)

  Maximum position distance for ports to be considered co-located.





**Returns:** `bool`

`True` if the ports can connect, `False` otherwise.