Using Python

KLayout does not come with one integrated interpreter. Instead Python and Ruby can both be used together. So it is possible to write one script in Ruby and another one in Python. Just pick your favorite language. Scripts written in different languages share the same KLayout data structures. Naturally they cannot directly share variables or language-specific data. But you can, for example, implement PCells in Python and Ruby and use those different PCells in the same layout at the same time. Depending on the type of PCell, KLayout will either execute Python or Ruby code.

Python macros are loaded into KLayout using either ".py" files or ".lym" files with the interpreter set to "Python". To create Python macros, a new tab is available in the Macro Development IDE. When creating macros in the "Python" tab, they will use the Python interpreter. Macros created in the "Ruby" tab will use the Ruby interpreter. Files loaded by "import" need to be in plain text format and use the ".py" suffix. The macro folder is called "pymacros" for a clean separation between the two macro worlds. Technically, both Ruby and Python macros are .lym files with a different interpreter specified in these files.

The Python macro folder is in the "sys.path" search path so it is possible to install modules there. To install libraries globally use "inst_path/lib/python/Lib" and "inst_path/lib/python/DLLs" on Windows. inst_path is the installation path (where klayout.exe is located). On Linux, the installation will share the Python interpreter with the system and modules installed there will be available for KLayout too.

"$PYTHONHOME" is not supported to prevent interference with other Python consumers. Instead, KLayout will read the Python path from "$KLAYOUT_PYTHONPATH" (for Python >= 3.x).

Writing Macros in Python

A good way is to start with the samples provided when creating new macros on the Python tab. The samples are available at the end of the template list. There is a sample for a PCell implementation, a sample for a Qt dialog, a sample for using Qt's .ui files in Python macros and one sample turning KLayout into a HTTP server using a Python macro.

Apart from a few specialities and the different language of course, Python macros do not look much different from Ruby macros. Ruby's "RBA" namespace is "pya" for Python (lowercase to conform with PEP-8). The class and methods names are the same with very few exceptions and the documentation can be used for Python too. Where necessary, a special remark is made regarding the Python implementation.

Here is a basic Python Macro. It creates a layout with a single cell and single layer and puts one rectangle on that layer:

# Python version:

import pya

layout = pya.Layout()
top = layout.create_cell("TOP")
l1 = layout.layer(1, 0)
top.shapes(l1).insert(pya.Box(0, 0, 1000, 2000))


Here is the Ruby variant to demonstrate the similarity:

# Ruby version:

layout = RBA::Layout::new()
top = layout.create_cell("TOP")
l1 = layout.layer(1, 0)
top.shapes(l1).insert(RBA::Box::new(0, 0, 1000, 2000))


Of course, not everything can be translated that easily between Ruby and Python. The details are given below. Usually however, it's straightforward to translate Ruby into Python.

There is no clear advantage of one language over the other. The Python community is somewhat stronger, but performance-wise, Ruby is better. In KLayout, the debugger support for Python is slighly better, since the guts of the interpreter are better documented for Python.

Apart from that, Python and Ruby coexist remarkably well and it is amazing, how easy it it to extend the interfaces from Ruby to Python: not counting the different in the memory management model (mark and sweep garbage collector in Ruby, reference counting in Python), the concepts are very similar.

Please read the Python specific notes below before you start. Some things need to be considered when going from Ruby to Python.

Python PCells

Please have a look at the PCell sample available in the templates. Pick the PCell sample after you have created a new Python macro.

PCell implementation in Python is very similar to Ruby.

Python macros are ".lym" files that are placed into the "pymacro" subfolder in the KLayout path. Python libraries can be put into the "python" subfolder. This subfolder is included into the "sys.path" variable, so macros can load libraries simply by using "import".

Python Implementation Notes