KFactory

2.4.6 · active · verified Fri Apr 17

KFactory is a Python library providing a high-level, Pythonic API for KLayout, a popular GDSII layout editor. It simplifies the creation and manipulation of GDSII layouts for chip design, acting as an abstraction layer over KLayout's native Python API (pya). It is often used in conjunction with `gdsfactory` for photonic integrated circuit (PIC) design. The library is actively maintained, with the current version being 2.4.6, and typically releases updates as new KLayout features are exposed or `gdsfactory` integration evolves.

Common errors

```
ERROR: Package 'kfactory' requires Python '>=3.11' but the currently active Python environment is '3.x'
```
cause Attempting to install `kfactory` in a Python environment older than 3.11.

fix Upgrade your Python environment to 3.11 or newer, or create a new virtual environment with a compatible Python version (e.g., `python3.11 -m venv .venv`).
```
ModuleNotFoundError: No module named 'pya'
```
cause The KLayout Python API (`pya`) is not found by your Python interpreter. This typically means KLayout is not installed, or its `pya` module's location is not included in your `PYTHONPATH`.

fix Install KLayout (the full GUI application, not just `klayout-python`). Then, either ensure KLayout's `pya` module directory is added to your `PYTHONPATH` environment variable, or run your Python script using KLayout's integrated Python environment (e.g., `klayout -r myscript.py`). Consult KLayout documentation for `pya` setup.
```
AttributeError: module 'kfactory.kcell' has no attribute 'Layer'
```
cause Attempting to access an older or non-existent layer API, such as `kf.kcl.Layer`. The current API for defining layers is a function, `kf.kcl.layer()`.

fix Use the `kf.kcl.layer(layer_id, datatype_id)` function to create KFactory layer objects. For instance, `my_layer = kf.kcl.layer(1, 0)`.

Warnings

gotcha KFactory requires Python 3.11 or newer. Attempting to install or run with older Python versions will result in installation failures or runtime errors.
Fix: Ensure your Python environment is 3.11 or newer. Consider using `pyenv` or virtual environments to manage Python versions.
gotcha KFactory is a wrapper around KLayout's native Python API (`pya`). You must have KLayout (the full GUI application) installed on your system, and its `pya` module needs to be discoverable by your Python environment (e.g., via `PYTHONPATH`). Without KLayout and `pya`, KFactory cannot function, leading to `ModuleNotFoundError` for `pya`.
Fix: Install KLayout from the official website. Ensure the directory containing KLayout's `pya` module (e.g., `C:\KLayout\klayout-0.x.x\bin` on Windows or `~/KLayout/klayout-0.x.x/lib/python/site-packages` on Linux/macOS, depending on KLayout installation method) is added to your `PYTHONPATH` environment variable. Alternatively, execute your KFactory script directly through KLayout's integrated Python environment using `klayout -r myscript.py`.
deprecated The API for defining layers has evolved. Older patterns like direct access to `kf.Layer` or `kf.kcell.Layer` (or attempting to instantiate them as classes) are deprecated or no longer function as expected. The correct and current method is to use the `kf.kcl.layer()` function.
Fix: Always use `kf.kcl.layer(layer_id, datatype_id)` to create KFactory layer objects. For example, `LAYER_1_0 = kf.kcl.layer(1, 0)`.

Install

pip install kfactory Install KFactory

Imports

kfactory
```
import kfactory as kf
```

KCell

import kfactory as kf
c = kf.KCell('my_cell')

layer
wrong:
```
import kfactory as kf
LAYER = kf.kcl.Layer(1,0)
```
correct:
```
import kfactory as kf
LAYER = kf.kcl.layer(1, 0)
```
The layer API is a function `kf.kcl.layer()`, not a class `kf.kcl.Layer()` or direct access to `kf.Layer` from older versions.

Quickstart

This quickstart demonstrates creating a basic KCell, defining a layer using the `kf.kcl.layer` API, adding a simple rectangle and text, and saving it to a GDSII file. The `c.show()` method is commented out but can be used to launch the KLayout GUI and view the cell directly, assuming KLayout is properly installed and discoverable.

import kfactory as kf
import os

c = kf.KCell('my_first_cell')

# Create a KLayout KCellLayer object for layer (1,0)
# Arguments are (layer_id, datatype_id)
LAYER_1_0 = kf.kcl.layer(1, 0)

# Add a rectangle to the cell on LAYER_1_0
# Coordinates are in nanometers (1000 = 1um, 2000 = 2um)
c.create_rectangle(LAYER_1_0, 1000, 2000)

# You can also add text
c.create_text("Hello KFactory!", LAYER_1_0, 1000)

# Save the cell to a GDSII file
output_gds_path = os.path.join(os.getcwd(), 'my_first_cell.gds')
c.write(output_gds_path)
print(f"GDSII file saved to: {output_gds_path}")

# To visualize, KFactory can launch KLayout if installed and configured
# Uncomment the line below to open the cell in KLayout GUI
# c.show()

view raw JSON →