Ports

A port marks a connection point on a cell — it records where another cell can attach to it. Every port stores:

Attribute	What it means
`name`	Human-readable identifier (`"o1"`, `"e_in"`, …)
`width`	Physical width of the waveguide / wire at this port
`layer`	GDS layer the port belongs to
`port_type`	`"optical"`, `"electrical"`, or any custom string
`trans` / `dcplx_trans`	Position + orientation (one of the two must be set)

kfactory ships two concrete port classes:

Class	Coordinate type	When to use
`Port`	DBU integers (nm)	Default — used by `KCell`
`DPort`	µm floats	When you prefer floating-point coordinates

import kfactory as kf


class LAYER(kf.LayerInfos):
    WG: kf.kdb.LayerInfo = kf.kdb.LayerInfo(1, 0)
    METAL: kf.kdb.LayerInfo = kf.kdb.LayerInfo(11, 0)
    FLOORPLAN: kf.kdb.LayerInfo = kf.kdb.LayerInfo(99, 0)


L = LAYER()
kf.kcl.infos = L

Creating a port

The most explicit way to create a port is to construct it directly. The orientation is encoded in a DCplxTrans (complex transformation in µm) or a plain Trans (DBU). The angle convention is:

Angle	Direction
`0°`	East (right) — port faces right, signal exits to the right
`90°`	North (up)
`180°`	West (left)
`270°`	South (down)

DCplxTrans(magnification, angle_deg, mirror, x_um, y_um):

port_left = kf.Port(
    name="o1",
    width=kf.kcl.to_dbu(1.0),  # 1 µm → DBU
    dcplx_trans=kf.kdb.DCplxTrans(1, 180, False, -5, 0),  # facing west at (-5, 0) µm
    layer=kf.kcl.find_layer(L.WG),
    kcl=kf.kcl,
)

port_right = kf.Port(
    name="o2",
    width=kf.kcl.to_dbu(1.0),
    dcplx_trans=kf.kdb.DCplxTrans(1, 0, False, 5, 0),  # facing east at (+5, 0) µm
    layer=kf.kcl.find_layer(L.WG),
    kcl=kf.kcl,
)

print(port_left)
print(port_right)

Port(self.name='o1', self.width=1000, trans=r180 *1 -5,0, layer=WG (1/0), port_type=optical)
Port(self.name='o2', self.width=1000, trans=r0 *1 5,0, layer=WG (1/0), port_type=optical)

Adding ports to a cell

Use cell.add_port(port=...) to attach a port to a cell. draw_ports() renders port markers so you can see direction and position in the notebook.

wg = kf.KCell(name="wg_ports_demo")
wg.shapes(kf.kcl.find_layer(L.WG)).insert(kf.kdb.DBox(-5, -0.5, 5, 0.5))
wg.add_port(port=port_left)
wg.add_port(port=port_right)

wg.draw_ports()
wg

Inspecting ports

cell.ports returns a Ports collection (list-like, with filtering helpers). Individual ports can be accessed by name using cell.ports["name"] or cell.port("name").

# List all ports
print(wg.ports)

["DPort(self.name='o1', self.width=1.0, trans=r180 *1 -5,0, layer=WG (1/0), port_type=optical)", "DPort(self.name='o2', self.width=1.0, trans=r0 *1 5,0, layer=WG (1/0), port_type=optical)"]

# Access by name
p = wg.ports["o1"]
print(f"name={p.name}  width={p.width} DBU  layer={p.layer_info}  angle={p.angle}°")

name=o1  width=1000 DBU  layer=WG (1/0)  angle=2°

# Inspect position in µm
print(f"x={p.x / wg.kcl.dbu**-1:.3f} µm, y={p.y / wg.kcl.dbu**-1:.3f} µm")
# or use the d-prefix convenience attributes:
print(f"dcplx_trans = {p.dcplx_trans}")

x=-5.000 µm, y=0.000 µm
dcplx_trans = r180 *1 -5,0

Port types

The port_type string distinguishes signal domains. kfactory uses "optical" and "electrical" by convention, but any string is valid. Routing functions use port_type to avoid accidentally connecting an optical port to an electrical one.

elec_port = kf.Port(
    name="e1",
    width=kf.kcl.to_dbu(2.0),
    dcplx_trans=kf.kdb.DCplxTrans(1, 180, False, -5, 3),
    layer=kf.kcl.find_layer(L.METAL),
    kcl=kf.kcl,
    port_type="electrical",
)
print(f"port_type = {elec_port.port_type}")

port_type = electrical

Filtering the `Ports` collection

Ports exposes several filter helpers — they all return a plain list[Port].

# Build a cell with a mix of optical and electrical ports
mixed = kf.KCell(name="mixed_ports")
mixed.shapes(kf.kcl.find_layer(L.WG)).insert(kf.kdb.DBox(-5, -0.5, 5, 0.5))

for name, angle, layer, ptype in [
    ("o1", 180, L.WG, "optical"),
    ("o2", 0, L.WG, "optical"),
    ("e1", 90, L.METAL, "electrical"),
    ("e2", 270, L.METAL, "electrical"),
]:
    mixed.add_port(
        port=kf.Port(
            name=name,
            width=kf.kcl.to_dbu(1.0),
            dcplx_trans=kf.kdb.DCplxTrans(1, angle, False, 0, 0),
            layer=kf.kcl.find_layer(layer),
            kcl=kf.kcl,
            port_type=ptype,
        )
    )

# Filter by port_type
optical = mixed.ports.filter(port_type="optical")
print("Optical ports:", [p.name for p in optical])

electrical = mixed.ports.filter(port_type="electrical")
print("Electrical ports:", [p.name for p in electrical])

Optical ports: ['o1', 'o2']
Electrical ports: ['e1', 'e2']

# Filter by angle (facing direction)
west_facing = mixed.ports.filter(angle=180)
print("West-facing ports:", [p.name for p in west_facing])

West-facing ports: []

# Filter by regex on port name
o_ports = mixed.ports.filter(regex="^o")
print("Ports starting with 'o':", [p.name for p in o_ports])

Ports starting with 'o': ['o1', 'o2']

Bulk port operations: `add_ports` and `copy_ports`

When placing instances inside a parent cell, you often want to expose the child's ports on the parent. add_ports copies ports from another collection, optionally adding a prefix to avoid name collisions.

parent = kf.KCell(name="two_wg_parent")

s = kf.cells.straight.straight(length=10, width=0.5, layer=L.WG)
wg1 = parent << s
wg2 = parent << s
wg2.transform(kf.kdb.DTrans(0, 5))  # shift 5 µm north (in DBU: 5000 nm)

parent.add_ports(wg1.ports, prefix="top_")
parent.add_ports(wg2.ports, prefix="bot_")

print([p.name for p in parent.ports])
parent.draw_ports()
parent

['top_o1', 'top_o2', 'bot_o1', 'bot_o2']

Auto-renaming ports

auto_rename_ports() reassigns port names following the gdsfactory convention: ports are numbered clock-wise starting from the bottom-left west-facing port. Optical ports get an o prefix, electrical ports get e.

parent.auto_rename_ports()
print([p.name for p in parent.ports])

['o1', 'o3', 'o2', 'o4']

Port-based placement with `connect`

instance.connect("port_name", other_port) moves and rotates the instance so that the named port aligns face-to-face with other_port. This is the primary way to assemble circuits without manually computing positions.

circuit = kf.KCell(name="connected_chain")

seg1 = circuit << kf.cells.straight.straight(length=10, width=0.5, layer=L.WG)
seg2 = circuit << kf.cells.straight.straight(length=15, width=0.5, layer=L.WG)
seg3 = circuit << kf.cells.straight.straight(length=10, width=0.5, layer=L.WG)

# Chain: seg2's o1 aligns with seg1's o2, then seg3's o1 aligns with seg2's o2
seg2.connect("o1", seg1.ports["o2"])
seg3.connect("o1", seg2.ports["o2"])

circuit.add_ports(seg1.ports, prefix="in_")
circuit.add_ports(seg3.ports, prefix="out_")
circuit.draw_ports()
circuit

Mirrored connections

Ports facing the same direction (not opposite) can be connected by specifying mirror=True. This reflects the instance before alignment — useful for symmetrical layouts.

bend = kf.cells.euler.bend_euler(radius=5, width=0.5, layer=L.WG, angle=90)

loop = kf.KCell(name="u_bend")
b1 = loop << bend
b2 = loop << bend
# Mirror b2 so both inputs face the same direction, forming a U-shape
b2.connect("o1", b1.ports["o2"], mirror=True)

loop.add_ports(b1.ports, prefix="left_")
loop.add_ports(b2.ports, prefix="right_")
loop.draw_ports()
loop

Summary

Operation	API
Create a port	`kf.Port(name=…, width=…, dcplx_trans=…, layer=…, kcl=kf.kcl)`
Attach to a cell	`cell.add_port(port=p)`
Access by name	`cell.ports["o1"]`
Filter by type / angle / regex	`cell.ports.filter(port_type=…, angle=…, regex=…)`
Expose child ports on parent	`parent.add_ports(inst.ports, prefix="…")`
Auto-rename	`cell.auto_rename_ports()`
Connect instance by port	`inst.connect("port_name", other_port)`
Visualise	`cell.draw_ports()`

Topic	Where
Placing and connecting instances with ports	Core Concepts: Instances
Cross-sections (port width + enclosure spec)	Cross-Sections
Optical routing between ports	Routing: Overview
Port-based component assembly	Components: Overview