Virtual PCells

A Virtual PCell (VKCell, short for Virtual KCell) is an in-memory PCell whose geometry lives entirely in floating-point micrometres — no KLayout database, no DBU conversion, until you explicitly materialise it.

┌──────────────────────────────────────────────┐
│               VKCell (µm)                    │
│  ┌──────────┐   ┌──────────┐                 │
│  │ VInstance│   │ VShapes  │  DPolygon, DBox │
│  └──────────┘   └──────────┘                 │
│        │             │                       │
│        ▼             ▼                       │
│   insert_into(real_kcell)                    │
└──────────────────────────────────────────────┘
          │
          ▼
   KCell (DBU, KLayout-backed)

When to use VKCell

Use case	Recommended cell type
Production GDS, routing into a final layout	`KCell`
All-angle routing backbone computation	`VKCell`
Preview / inspect before committing geometry	`VKCell`
Factory functions that need composition before materialisation	`VKCell`

Key differences vs KCell

Property	`VKCell`	`KCell`
Coordinates	float µm	integer DBU
Backed by KLayout cell DB	No — pure Python	Yes
Shape type	`VShapes` (`DPolygon`, `DBox`, …)	`klayout.db.Shapes`
`@kf.vcell` / `kcl.vcell` decorator	Yes	No (`@kf.cell`)
Must call `insert_into()` to materialise	Yes	—

Setup

from functools import partial

import kfactory as kf
from kfactory.factories.virtual.euler import virtual_bend_euler_factory
from kfactory.factories.virtual.straight import virtual_straight_factory


class LAYER(kf.LayerInfos):
    WG: kf.kdb.LayerInfo = kf.kdb.LayerInfo(1, 0)
    WGCLAD: kf.kdb.LayerInfo = kf.kdb.LayerInfo(2, 0)


L = LAYER()

# Use a dedicated KCLayout so the virtual factories' layer indices are consistent
pdk = kf.KCLayout("virtual_demo", infos=LAYER)

Creating a VKCell directly

kcl.vkcell(name=...) returns an empty VKCell attached to the given layout. Shapes are added via vkcell.shapes(layer_index).insert(...) using µm-based DPolygon / DBox objects.

vc_box = pdk.vkcell(name="simple_box")

layer_idx = pdk.layer(L.WG)

# Insert a rectangle in µm
vc_box.shapes(layer_idx).insert(kf.kdb.DBox(0, -0.25, 10.0, 0.25))

print(f"VKCell name  : {vc_box.name}")
print(f"bbox (µm)    : {vc_box.dbbox(layer_idx)}")
print(f"bbox (DBU)   : {vc_box.ibbox(layer_idx)}")
print(f"shapes count : {vc_box.shapes(layer_idx).size()}")

VKCell name  : simple_box
bbox (µm)    : (0,-0.25;10,0.25)
bbox (DBU)   : (0,-250;10000,250)
shapes count : 1

Notice that ibbox returns the bounding box in DBU (integer units), while dbbox returns it in µm. The two are consistent — multiplied by pdk.dbu (nm/µm).

Ports on a VKCell

Ports are created with create_port using a DCplxTrans (µm-based complex transform) to specify position and orientation.

vc_wg = pdk.vkcell(name="virtual_wg")
wg_layer = pdk.layer(L.WG)

vc_wg.shapes(wg_layer).insert(kf.kdb.DBox(0, -0.25, 20.0, 0.25))

# o1 faces west (angle=180°)
vc_wg.create_port(
    name="o1",
    dcplx_trans=kf.kdb.DCplxTrans(1, 180, False, 0.0, 0.0),
    width=0.5,
    layer=wg_layer,
)
# o2 faces east (angle=0°)
vc_wg.create_port(
    name="o2",
    dcplx_trans=kf.kdb.DCplxTrans(1, 0, False, 20.0, 0.0),
    width=0.5,
    layer=wg_layer,
)

for p in vc_wg.ports:
    print(f"  {p.name}: trans={p.dcplx_trans}  width={p.dwidth:.3f} µm")

  o1: trans=r180 *1 0,0  width=0.500 µm
  o2: trans=r0 *1 20,0  width=0.500 µm

Materialising into a KCell

Call VInstance(vc).insert_into(target) to convert the virtual geometry to a real KCell instance inside target. This is a one-shot operation — you can call it multiple times to place the virtual cell at different locations.

target = kf.KCell("wg_from_virtual", kcl=pdk)
vi = kf.VInstance(vc_wg)
vi.insert_into(target)

print(f"Real cell name  : {target.name}")
print(f"Real cell bbox  : {target.dbbox()} µm")
target.plot()

Real cell name  : wg_from_virtual
Real cell bbox  : (0,-0.25;20,0.25) µm

Nesting VKCells

VKCells can contain instances of other VKCells. The whole hierarchy is flattened into real KLayout cells when insert_into is called on the outermost level.

# Build two virtual waveguide arms
arm_a = pdk.vkcell(name="arm_a")
arm_a.shapes(wg_layer).insert(kf.kdb.DBox(0, -0.25, 30.0, 0.25))

arm_b = pdk.vkcell(name="arm_b")
arm_b.shapes(wg_layer).insert(kf.kdb.DBox(0, -0.25, 30.0, 0.25))

# Compose them inside a parent virtual cell
parent_vc = pdk.vkcell(name="virtual_composed")
inst_a = parent_vc.create_inst(cell=arm_a)  # at (0, 0)
inst_b = parent_vc.create_inst(
    cell=arm_b,
    trans=kf.kdb.DCplxTrans(1, 0, False, 0.0, 2.0),  # shift 2 µm up
)

print(f"parent bbox (µm): {parent_vc.dbbox()}")

# Materialise the whole hierarchy at once
c_composed = kf.KCell("composed_from_virtual", kcl=pdk)
kf.VInstance(parent_vc).insert_into(c_composed)
c_composed.plot()

parent bbox (µm): (0,-0.25;30,2.25)

`@kf.vcell` decorator

For reusable virtual component factories use the @pdk.vcell decorator — it works like @pdk.cell but returns a VKCell and caches by parameter hash.

@pdk.vcell
def virtual_straight(
    width: float,
    length: float,
    layer: kf.kdb.LayerInfo,
) -> kf.VKCell:
    c = pdk.vkcell()
    lyr = pdk.layer(layer)
    half_w = width / 2
    c.shapes(lyr).insert(kf.kdb.DBox(0, -half_w, length, half_w))
    c.create_port(
        name="o1",
        dcplx_trans=kf.kdb.DCplxTrans(1, 180, False, 0.0, 0.0),
        width=width,
        layer=lyr,
    )
    c.create_port(
        name="o2",
        dcplx_trans=kf.kdb.DCplxTrans(1, 0, False, length, 0.0),
        width=width,
        layer=lyr,
    )
    return c


s1 = virtual_straight(width=0.5, length=10.0, layer=L.WG)
s2 = virtual_straight(width=0.5, length=10.0, layer=L.WG)  # cached

print(f"s1 is s2 (cached): {s1 is s2}")
print(f"s1 bbox : {s1.dbbox(pdk.layer(L.WG))} µm")

s1 is s2 (cached): True
s1 bbox : (0,-0.25;10,0.25) µm

Virtual factories

kfactory ships built-in virtual factories for straight waveguides and euler bends. These are the building blocks for all-angle routing (see All-Angle Routing).

Factory	Source module	Parameter units
`virtual_straight_factory(kcl)`	`kfactory.factories.virtual.straight`	µm
`virtual_bend_euler_factory(kcl)`	`kfactory.factories.virtual.euler`	µm

_v_straight_raw = virtual_straight_factory(kcl=pdk)
_v_bend_raw = virtual_bend_euler_factory(kcl=pdk)

# Bind common parameters with functools.partial
v_straight = partial(_v_straight_raw, layer=L.WG)
v_bend = partial(_v_bend_raw, width=0.5, radius=10.0, layer=L.WG)

# Produce virtual components
vs = v_straight(width=0.5, length=15.0)
vb = v_bend(angle=90)

print(f"virtual straight bbox : {vs.dbbox(pdk.layer(L.WG))} µm")
print(f"virtual bend    bbox  : {vb.dbbox(pdk.layer(L.WG))} µm")
print(f"virtual bend    ports : {[p.name for p in vb.ports]}")

virtual straight bbox : (0,-0.25;15,0.25) µm
virtual bend    bbox  : (0,-0.25;18.9509584665,18.7009584665) µm
virtual bend    ports : ['o1', 'o2']

All-angle routing into a VKCell

The most common reason to work with VKCell directly is all-angle routing — computing the route in virtual space, inspecting it, then materialising once satisfied.

vc_route = pdk.vkcell(name="aa_preview")

kf.routing.aa.optical.route(
    vc_route,
    width=0.5,
    backbone=[
        kf.kdb.DPoint(0, 0),
        kf.kdb.DPoint(80, 0),
        kf.kdb.DPoint(80, 60),
        kf.kdb.DPoint(160, 60),
    ],
    straight_factory=v_straight,
    bend_factory=v_bend,
)

print(f"Virtual route bbox (µm): {vc_route.dbbox()}")
print(f"Ports: {[p.name for p in vc_route.ports]}")

# Materialise into a real cell
c_aa = kf.KCell("aa_from_vkcell", kcl=pdk)
kf.VInstance(vc_route).insert_into(c_aa)
c_aa.plot()

Virtual route bbox (µm): (0,-0.25;160,60.25)
Ports: []

`insert_into_flat`

Use insert_into_flat when you want the virtual geometry inlined directly into the target cell (no sub-cell hierarchy created).

c_flat = kf.KCell("aa_flat", kcl=pdk)

vc_flat = pdk.vkcell(name="route_flat_src")
kf.routing.aa.optical.route(
    vc_flat,
    width=0.5,
    backbone=[
        kf.kdb.DPoint(0, 0),
        kf.kdb.DPoint(50, 0),
        kf.kdb.DPoint(50, 40),
        kf.kdb.DPoint(100, 40),
    ],
    straight_factory=v_straight,
    bend_factory=v_bend,
)

kf.VInstance(vc_flat).insert_into_flat(c_flat)

print(f"Instances in c_flat : {list(c_flat.each_inst())}")
print(f"c_flat bbox (µm)    : {c_flat.dbbox()}")
c_flat.plot()

Instances in c_flat : []
c_flat bbox (µm)    : (0,-0.25;100,40.25)

With insert_into_flat all geometry lands directly in c_flat — no child cells are created.

Summary

Operation	Code
Create VKCell	`vc = kcl.vkcell(name="...")`
Insert shape	`vc.shapes(layer_idx).insert(kdb.DBox(...))`
Add port	`vc.create_port(name=..., dcplx_trans=..., width=..., layer=...)`
Nest VKCells	`vc.create_inst(cell=child_vc, trans=...)`
Reusable factory	`@pdk.vcell` decorator
Materialise (hierarchical)	`kf.VInstance(vc).insert_into(target)`
Materialise (flat)	`kf.VInstance(vc).insert_into_flat(target)`
Virtual straight factory	`virtual_straight_factory(kcl=pdk)`
Virtual euler bend factory	`virtual_bend_euler_factory(kcl=pdk)`

Topic	Where
PCells & caching	Components: PCells
Factory functions reference	Components: Factories
All-angle routing into VKCell	Routing: All-Angle
KCell / DKCell / VKCell basics	Core Concepts: KCell