kfactory vs gdsfactory
kfactory is based on KLayout and therefore has quite a few fundamental differences to gdsfactory.
A Components in gdsfactory corresponds to a KCell in kfactory. ComponentReference is represented in kfactory as an Instance.
KCLayout / KCell / Instance
KLayout uses a Layout object as a base. Cells (and KCells) must have a Layout as a base, they cannot work without one. Therefore a KCell will always be attached to a KCLayout which is an extension of a Layout object. kfactory provides a default KCLayout objecti kfactory.kcl which all KCells not specifying another KCLayout in the constructor will use.
This KCLayout object contains all KCells and also keeps track of layers.
Similar as a KCell cannot exist without a KCLayout, an Instance cannot exist without being part of a KCell. It must be created through the KCell
Layers
Compared to gdsfactory, KLayout needs to initialize new layers. Layers are always associated or part of one KCLayout. They cannot be shared
or used in another KCLayout without a function that specifically copies from one KCLayout to another.
It can either by done directly in the KCLayout object with kcl.layer(layernumber, datatype) which will return an integer. This integer
is the internal index of the layer, meaning KLayout will keep layers in a mapping (dictionary) like structure.
kfactory also provides an enum class LayerEnum to do the mapping to the (default) KCLayout. This can either be done in the standard enum way
LayerEnum
class LAYER(kfactory.LayerEnum):
WG = (1, 0)
WGEXCLUDE = (1, 1)
Or it can be done dynamically with a slightly more complex syntax.
Dynamic LayerEnum
LAYER = kfactory.LayerEnum("LAYER", {"WG": (1, 0), "WGEXCLUDE": (1, 1)})
The first argument represents the name of the enum that will be used for the __str__ or __repr__ methods. It is strongly recommended to name it the same as the variable
it is assigned to. This will make sure the behavior is the same as the first construction way.i
The LayerEum also allows mapping from string to layer index and layer number and datatype:
Accessing LayerEnum by index or name and getting layer number & datatype
>>> LAYER = kfactory.LayerEnum("LAYER", {"WG": (1,0), "WGEXCLUDE": (1,1)})
>>> LAYER.WG
<LAYER.WG: 0>
>>> LAYER["WG"]
<LAYER.WG: 0>
>>> LAYER(0)
<LAYER.WG: 0>
>>> LAYER.WG.datatype
0
>>> LAYER.WG.layer
1
Layer Indexes
In KLayout it is possible to push shapes or other layer associated objects into layer indexes that don't exist (yet or even ever). Therefore always use either the LayerEnum
to access a shapes object or use the KLayout tools too do so. E.g. shapes on layer (1,0) can either be accessed with c.shapes(LAYER.WG) or c.shapes(c.kcl.layer(1,0)).
It is never good practice to do c.shapes(0) even if layer index 0 exists. If you import this module later on, index 0 might be something else, or worse even, be deleted.
Shapes
In contrast to gdsfactory, every geometrical dimension is represented as an object. All the objects are available in two flavors. Integer based for the mapping to the grid of gds/oasis in database units (dbu) or floating version based on micrometer.
| Object (dbu) | Object (um) | Description |
|---|---|---|
| Point | DPoint | Holds x/y coordinate in dbu |
| Vector | DVector | Similar to a point, but can be used for geometry operations and can be multiplied |
| Edge | DEdge | Connection of two points (p1/p2), is aware of the two sides |
| Box | DBox | A rectangle defined through two points. Rotating a box will result in a bigger box |
| SimplePolygon | DSimplePolygon | A polygon that has no holes (this is what all polygons will be converted to when inserting) |
| Polygon | DPolygon | Like the simple polygon but this one can have holes and allows operations like sizing |
| Text | DText | Labels. They can have a full transformations, but KLayout doesn't show full transformations by default |
| Shape | - | A generalized container for other geometric objects that allows storage and retrieval |
| Shapes | - | A flat collection of shapes. Used by KCells to access shapes in a cell |
| Region | - | Flat or deep collection of polygons. Any other dbu shape can be inserted (except Texts) |
In kfactory and KLayout these object can live outside of a (K)Cell. Therefore it is not possible to create them through the KCell like in gdsfactory.
These objects can be inserted into a KCell with c.shapes(layer_index).insert(shabpe_like_object).
gdsfactory's add_polygon in kfactory
In gdsfactory polygons are usually created through c.add_polygon(pts, layer_tuple). In kfactory this is not directly possible, nor very useful,
as not all geometrical objects are polygons. Additionally, kfactory and KLayout don't know layers without a datatype and integers alone are interpreted
as layer indexes not as a (layer_number, 0) tuple.
In kfactory a Polygon can be created like this and then inserted into KCell c with c.shapes(layer_index).insert(polygon). Since the objects are not linked
to any KCell, they can be used multiple times. Using the LAYER object from above, code could look like this:
Polygon
# dbu based
points = [kfactory.kdb.Point(x, y) for x, y in [(0, 0), (1000, 0), (500, 500)]]
polygon = kfactory.kdb.Polygon(points)
c.shapes(LAYER.WG).insert(polygon)
c.shapes(LAYER.WGEXCLUDE).insert(polygon)
# um based
dpoints = [kfactory.kdb.DPoint(x, y) for x, y in [(0, 0), (1000, 0), (500, 500)]]
dpolygon = kfactory.kdb.DPolygon(dpoints)
c.shapes(LAYER.WG).insert(dpolygon)
c.shapes(LAYER.WGEXCLUDE).insert(dpolygon)
Due to the verbosity of this code, kfactory provides convenience function for polygons and dpolygons to convert arrays of shap [n, 2] into a
(D)Polygon directly:
Polygon from Array
# dbu based
polygon = kfactory.polygon_from_array([(0, 0), (10, 0), (5, 5)])
c.shapes(LAYER.WG).insert(polygon)
c.shapes(LAYER.WGEXCLUDE).insert(polygon)
# um based
dpolygon = kfactory.dpolygon_from_array([(0, 0), (10, 0), (5, 5)])
c.shapes(LAYER.WG).insert(dpolygon)
c.shapes(LAYER.WGEXCLUDE).insert(dpolygon)
gdsfactory's add_label in kfactory
Similar to the add_polygon function, add_label as a text record to a cell. Due to the nature of the layer number alone in gdsfactory vs layer index in kfactory,
there is no add_label in kfactory. Instead they can be used like any other shape object.
Text
# dbu based
c.shapes(LAYER.WG).insert(kfactory.kdb.Text("any string here", x_dbu, y_dbu))
# um based
c.shapes(LAYER.WG).insert(kfactory.kdb.DText("any string here", x_um, y_um))
Connecting Ports
kfactory also offers c.connect(port_name, other_port) like gdsfactory does. It doesn't exactly do the same thing as in gdsfactory though. A Port
in kfactory will always try to be on grid. Additionally the port is using kfactory.kdb.Trans and kfactory.kdb.DCplxTrans by default, similar to an instance.
This also means that a port is aware of mirroring. Since a connect can be simplified to instance.trans = other_port.trans * kfactory.kdb.Trans.R180 * port.trans.inversed()
(for the 90° on-grid cases), it can be seen that the center, angle and mirror flag of the instance is overwritten. Therefore, any move / rotation / mirror on the instance
connect is called on, will have no influence on the state after the connect.
Also, as with gdsfactory connect is not final. It does not imply any shared link between the instances after the connect, it is simply a transformation with some checks
about layer, width and port type matching.
Example
# inst1,inst2 are instances
# connect inst1 "o1" to inst2 "o2"
inst1.connect("o1", inst2.ports["o2"])
# also possible
inst1.connect("o1", inst2, "o2")
### If inst2 "o2" had trans.is_mirror() == True, inst1's transformation now also has is_mirror() == True
LayerEnclosure / KCellEnclosure vs CrossSection
kfactory doesn't have the concept of cross sections. since cross sections are limited to have a path as a backbone, kfactory implemented a more generalized form as enclosures. LayerEnclosures can use regions or even entire layers as a basis to apply excludes and claddings (or anything that depends on the base form). Additionally, kfactory has the extended concept of KCellEnclosure. These can apply enclosures to a whole KCell on all layers the KCellEnclosure is aware of. For further info, please head over to the Tutorial