Macro and script development

KLayout macros are Python scripts which can be run inside KLayout Editor. They can be used, for example, to create or modify elements in the layout, measure properties of cells, or export data from the layout. See also the KLayout documentation about macro development and programming scripts , and the KLayout API documentation.

Stand-alone python scripts can also be used to generate and export geometry if KQCircuits is installed as a python library. See Developer Standalone module Setup for details.

Running the first example

To get started, follow the steps below to run a demo macro. The comments in the macro explain what is going on step by step.

  1. Open the KLayout application

  2. From the top menu, choose “Macros” and “Macro Development”, or press F5.

  3. Select “Python”

  4. Open “[Local - python branch]”, where you should see the “kqcircuits scripts” directory

  5. Open kqcircuits_scripts/macros/generate/demo_placing_a_pcell.lym

  6. Make sure debugging mode is off (bug icon is not pressed in)

  7. Click on the green play symbol with the exclamation mark (“Run script from the current tab”), or use Shift+F5.

  8. A chip cell should appear in the main KLayout window.

Interacting with the KLayout application

KLayout organizes layouts in Panels, which show as tabs in the application if more than one panel is open. In code, the panel is represented by a LayoutView object. Inside each panel there can be one or more layouts loaded, for example with the File, Open in Same Panel command. Each layout is represented by a CellView object and a Layout object. The Layout contains all the actual cells, layers and shapes.

As shown by the above, to work with the KLayout display in macro code we need access to at least three objects. To help in managing this, KQCircuits provides the class KLayoutView.

Creating a new panel

Often, in a macro you want to start with a new layout in a new panel, which can be created as follows:

from kqcircuits.klayout_view import KLayoutView
view = KLayoutView()

This code creates a panel, cell view and layout, and initializes these with the layers used by KQCircuits.

Accessing the currently active panel

In some macros you may want to interact with the layout that is currently visible. In this case, use:

from kqcircuits.klayout_view import KLayoutView
view = KLayoutView(current=True)

Using KLayoutView

Once created, KLayoutView exposes methods for the most common tasks to do with a layout:

  • insert_cell places KQCircuits elements into the top cell, similar to Element.insert_cell.

  • focus makes sure a particular cell or the entire layout is visible (zoom to fit and show all hierarchy levels).

  • show shows the panel associated with this object, in case there are multiple panels open

  • export_pcell_png exports an image of a cell to a file

See the KLayoutView API documentation for all methods and their usage.

If more advanced interaction with KLayout is needed, the KLayout API objects are exposed as properties. See the corresponding KLayout API documentation linked below for their usage details:

  • layout_view: The LayoutView instance, which refers to a panel in the KLayout GUI.

  • cell_view: The CellView instance. In case a panel has multiple cell views (for example when multiple files are opened in the same panel), this returns the currently active one.

  • layout: The Layout object is the main container for cells, layers and geometry

  • top_cell: A reference to the first top Cell of the layout. This is the very first cell shown in the cell window. Usually we place elements in this cell.

  • active_cell: A reference to the currently active cell. This is the cell which is shown in bold in the cell window, and can be changed in KLayout by right-clicking a cell and choosing Show As New Top.

Debugger

KLayout macros can be debugged using the debugger in the macro IDE. The debugger can be toggled on/off using the “bug icon” at the top.

  • Basic debugger workflow

    1. Place breakpoint in the code (red circle icon or F9).

    2. Run the macro.

    3. Execution will stop at the breakpoint. The values of all variables at that point are now visible in the “Local variables” panel. You can also double-click on the lines in the “Call stack” panel, to see variable values at other stages of the call stack.

    4. Can place more breakpoints, and the macro will stop at the next one when you run the macro again.

    5. Can also use the “Step over” and “Step into” buttons (icons with arrows inside files or F) to go through the code step-by-step.

  • If an exception is raised when running a macro, you will get a pop-up error window. By pressing “Cancel”, you will get the debugger view at the point where the exception was raised, as if there was a breakpoint there.

  • PCells can sometimes have errors in their code, which will be visible in the layout as missing parts and an asterisk at the end of the cell name. These errors can be caught by having the macro window open and debugger on when the PCell is placed into the layout.

    Note

    • For this to work the PCell must be created from instance menu on the top. If the PCell is dragged from “Libraries” panel, KLayout will become unresponsive after the error is caught.

    • Errors will not be caught if creating a new PCell with the exact same parameters as a previous one, because the PCell code runs only the first time it is created.

Note

The debugger will slow down code execution, so it can make sense to disable it when running heavy macros.

Reloading libraries

  • Even though you have changed some line inside a PCell file, if nothing changes on the generated design inside the editor, you have to re-run the reload.lym file to be able to reload the library features for changes to be updated. The reload macro can also be run from “KQCircuits -> Reload libraries” in the main KLayout window

  • The libraries are automatically reloaded whenever you restart KLayout, so in that case there is no need to run the reload macro to see changes.

Examples