Add parameter names to markers in documentation

[qpavsmi]

Prerequisites

• Requires standalone KQCircuits installation, make sure to include the docs package.
• GUI KQCircuits installation highly recommended.

Issue description

We illustrate the chip elements we provide in KQCircuits by generating screencaptures of their geometry during documentation generation, take waveguide_coplanar_taper for example. We also provide a mechanism to highlight certain features of such elements that we deem important. Currently we present the scale of such features by illustrating a ruler, i.e. a line between two points with the distance between these points written down. We would like to extend this mechanism to also label such ruler elements by the parameter names that define that geometry feature. See below for how the final result could look like:

How to get started

cd to <KQCircuits source folder>/docs and run make html. This will generate documentation html pages that we host in https://iqm-finland.github.io/KQCircuits/index.html . You can try out your locally generated documentation KQCircuits documentation by opening the <KQCircuits source folder>/docs/_build/html/index.html with the browser application of your choice.

We keep the source file for the text content of the documentation in docs folder, but the API documentation chapter is generated automatically from the docstrings of the source code files. This chapter also houses automatically generated illustrations of the elements contained in the KQCircuits library. These illustrations are generated by make_pcell_images.py script, which spawns multiple pcell2png.py scripts in parallel for each element script in the KQCircuits source code.

In the docstrings of some of the elements we include a MARKERS_FOR_PNG keyword in the class docstring, as seen in waveguide_coplanar_taper.py. With this keyword the illustration of the element will also contain ruler markers, which are lines between two points with the distance between these points written down. The MARKERS_FOR_PNG keyword is followed by sets of numbers, each set being separated by whitespace and numbers within the set separated by comma , characters. Each set of numbers contains either four or two numbers. If four numbers are used, a ruler is drawn between two 2D coordinates given (x1,y1,x2,y2). If two numbers are used, it is interpreted as a single 2D coordinate, from which a measurement line is found automatically extending to two opposite directions from the given point, see KLayout's create_measure_ruler method. The MARKERS_FOR_PNG keyword is processed in the pcell2png.py script.

The task is to extend the expected format of the MARKERS_FOR_PNG keyword to configure the label text near the illustrated ruler, signifying which parameter causes the distance illustrated by the ruler to change. The expected format could be MARKERS_FOR_PNG x1,y1,x2,y2,text ... or MARKERS_FOR_PNG x,y,text ... An example use case for waveguide_coplanar_taper.py is MARKERS_FOR_PNG 0,0,31.2,0,taper_length 0,5,0,-5,a 31.2,-10,31.2,10,a2 (it is reasonable to assume that parameter names won't have a comma , character). The solution could be to reconfigure the Annotation objects that are placed in the layout to include text. If that is not feasible, text objects could be placed on a separate layer e.g. "marker_labels". In that case the new layer should be configured as a default layer in default_layer_config.py in the _aux_layers_dict dict. Please also use the check_layer_props.py utility script (with -w option) to configure the new layer to use correct colors etc.

Changing all instances of MARKERS_FOR_PNG use in KQCircuits to include the text is not required but is very much appreciated. It would require some research on the parameters of each such element, either by studying the API docs, the element class code, or by trying out changing parameter values from UI. Please use parameter names (e.g. a) rather than their descriptions (e.g. Width of center conductor). In case you would be so kind to do this, the following is a list of all of its current use:

• elements/airbridge_connection.py
• elements/chip_frame.py
• elements/circular_capacitor.py
• elements/finger_capacitor_square.py
• elements/finger_capacitor_taper.py
• elements/launcher_dc.py
• elements/launcher.py
• elements/meander.py
• elements/waveguide_composite.py
• elements/waveguide_coplanar_curved.py
• elements/waveguide_coplanar_splitter.py
• elements/waveguide_coplanar_straight.py
• elements/waveguide_coplanar_taper.py
• elements/waveguide_coplanar.py
• elements/airbridges/airbridge_multi_face.py
• elements/airbridges/airbridge_rectangular.py
• elements/flip_chip_connectors/flip_chip_connector_dc.py
• elements/flip_chip_connectors/flip_chip_connector_rf.py
• elements/fluxlines/fluxline_standard.py
• elements/fluxlines/fluxline_straight.py
• elements/markers/marker_standard.py
• elements/tsvs/tsv_ellipse.py
• elements/tsvs/tsv_standard.py
• qubits/swissmon.py

Definition of done

• Extend MARKERS_FOR_PNG keyword parsing to also have a text value configured for each marker
• The text argument should be optional, so that old instances of MARKERS_FOR_PNG keyword would be functional (required even if all instances of the keyword are updated)
• The text should be visible in the documentation pages near its respective ruler marker. Preferably the text should be automatically positioned in a clear enough spot without the need of configuring text location separate from the ruler location.
• Documentation entry explaining usage of MARKERS_FOR_PNG (docs/developer/documentation.rst) should be updated
• There should be at least one use of the new MARKERS_FOR_PNG parsing included in the PR. Reconfiguring all instances of MARKERS_FOR_PNG is not required, but appreciated.
• No tests needed

[lavanya-m-k]

I would like to work on this issue. Can you please assign it to me?

[qpavsmi]

I would like to work on this issue. Can you please assign it to me?

Yes and thank you for your interest! You can start working on the solution and once the solution is ready, create a pull request. During review we might give some suggestions to refine the solution, but once it is ready, we will assign you to this issue and mark it closed. Don't hesitate to make a pull request earlier rather than later so that we could have some time before the deadline to reiterate your solution from our feedback if needed.

[iqmtestd]

@lavanya-m-k Do you still intend to fix this issue or may I take it over?