Returns layer info of given name. If layer doesn’t exist, a new layer is created. New layers are created with data type = 0 and layer numbering starts from 1000.

class kqcircuits.simulations.simulation.Simulation(layout, **kwargs)[source]

Bases: object

Base class for simulation geometries.

Generally, this class is intended to be subclassed by a specific simulation implementation; the implementation defines the simulation geometry ad ports in build.

A convenience class method Simulation.from_cell is provided to create a Simulation from an existing cell. In this case no ports will be added.

Basically, 3D layout is built of substrates, which are separated from each other by vacuum boxes, however, this rule is modifiable by setting substrate and vacuum thicknesses to zero. In principle, one can stack faces on any of the imaginable surface of a substrate. If substrate or vacuum thickness is set to zero, then there can be two faces touching each other. Faces can be stacked on bottom or top surface of the substrates.

Number of substrate and vacuum boxes are determined with parameters face_stack and lower_box_height: - If lower_box_height > 0, there will be a vacuum box below the lowest substrate, and the counting of faces will start from the bottom surface of the lowest substrate. Otherwise, the lowest substrate will be below the lowest vacuum box, and the counting of faces will start from the top surface of the lowest substrate. - Length of face_stack list describes how many surfaces are taken into account in the simulation.

The terms in the face_stack indicate in which order the klayout faces are stacked in the 3D layout. Faces are counted from the lowest substrate surface to the highest. One can also introduce face_stack as list of lists. If a term in face_stack is a list, then all the faces given in the list are piled up on the corresponding surface in the respective order. That means, the first term in the inner list indicates the face that is closest to the surface of the substrate. One can use empty list in face_stack to leave certain surface without metallization.

Heights of substrates (substrate_height) and vacuum boxes between surfaces (chip_distance) can be determined individually from bottom to top or with single value. Any of the heights can be left zero, to indicate that there is no vacuum between the substrates or substrate between the vacuum boxes. Also, the metal thickness (metal_height) can be set to zero, but that means the metal layer is modelled as infinitely thin sheet. The insulator dielectric can be set on any metal layer if non-zero dielectric_height is given.

Initialize a Simulation.

The initializer parses parameters, creates a top cell, and then calls self.build to create the simulation geometry, followed by self.create_simulation_layers to process the geometry so it is ready for exporting.


layout – the layout on which to create the simulation

Keyword Arguments


Any parameter can be passed as a keyword argument.

In addition, cell can be passed as keyword argument. If cell is supplied, it will be used as the top cell for the simulation. Otherwise, a new cell will be created. See Simulation.from_cell for creating simulations from existing cells.

ports: List[kqcircuits.simulations.port.Port]
classmethod from_cell(cell, margin=300, grid_size=1, **kwargs)[source]

Create a Simulation from an existing cell.

  • cell – existing top cell for the Simulation

  • margin – distance (μm) to expand the simulation box (ground plane) around the bounding box of the cell If the box keyword argument is given, margin is ignored.

  • grid_size – size of the simulation box will be rounded to this resolution If the box keyword argument is given, grid_size is ignored.

  • **kwargs – any simulation parameters passed


Simulation instance

abstract build()[source]

Build simulation geometry.

This method is to be overridden, and the overriding method should create the geometry to be simulated and add any ports to self.ports.

classmethod get_schema(noparents=False, abstract_class=None)

Returns the combined parameters of the class “cls” and all its ancestor classes.

  • noparents – If True then only return the parameters of “cls”, not including ancestors.

  • abstract_class – Return parameters up to this abstract class if specified.


Returns the face dictionary corresponding to self.face_ids[face_index].

The face dictionary contains key “id” for the face ID and keys for all the available layers in that face.


face_index – index of the face_id in self.face_ids, default=0

insert_cell(cell, trans=None, inst_name=None, label_trans=None, align_to=None, align=None, rec_levels=0, **parameters)

Inserts a subcell into the present cell.

It will use the given cell object or if cell is an Element class’ name then directly take the provided keyword arguments to first create the cell object.

If inst_name given, the refpoints of the cell are added to the self.refpoints with inst_name as a prefix, and also adds a label inst_name to “`”labels layer” at the base refpoint and label_trans transformation.

  • cell – cell object or Element class name

  • trans – used transformation for placement. None by default, which places the subcell into the coordinate origin of the parent cell. If align and align_to arguments are used, trans is applied to the cell before alignment transform which allows for example rotation of the cell before placement.

  • inst_name – possible instance name inserted into subcell properties under id. Default is None

  • label_trans – relative transformation for the instance name label

  • align_to – location in parent cell coordinates for alignment of cell. Can be either string indicating the parent refpoint name, DPoint or DVector. Default is None

  • align – name of the cell refpoint aligned to argument align_to. Default is None

  • rec_levels – recursion level when looking for refpoints from subcells. Set to 0 to disable recursion.

  • **parameters – PCell parameters for the element, as keyword argument


tuple of placed cell instance and reference points with the same transformation

get_refpoints(cell, cell_transf=r0 0, 0, rec_levels=None)

See get_refpoints.

add_element(cls, **parameters)

Create a new cell for the given element in this layout.

  • cls – Element subclass to be created

  • **parameters – PCell parameters for the element as keyword arguments


the created cell

get_layer(layer_name, face_id=0)

Returns the specified Layer object.

  • layer_name – layer name text

  • face_id – Name or index of the face to use, default=0

pcell_params_by_name(cls=None, **parameters)

Give PCell parameters as a dictionary.

  • cls – Return only parameters present in this class. All by default.

  • **parameters – Optionally update with other keyword arguments


A dictionary of all PCell parameter names and corresponding current values.


Return self.face_stack forced to be list of lists

static ith_value(list_or_constant, i)[source]

Helper function to return value from list or constant corresponding to the ordinal number i. Too short lists are extended by duplicating the last value of the list.


Returns dictionary of z-levels. The dictionary can be used either with integer or string key values: Integer keys return surface z-levels in ascending order (including domain boundary bottom and top). String keys (key = face_id) return the three z-levels of the face (metal bottom, metal-dielectric interface, dielectric top)

The level z=0 is at lowest substrate top.

region_from_layer(face_id, layer_name)[source]

Returns a Region containing all geometry from a specified layer

simplified_region(region, expansion=0.0)[source]

Returns a region that is simplified by functions region_with_merged_polygons and region_with_merged_points. More precisely: - Merges polygons ignoring gaps that are smaller than self.polygon_tolerance - Expands/shrinks region by amount given by ‘expansion’ - In each polygon of the region, removes points that are closer to other points than self.minimum_point_spacing

insert_layer(region, layer_name, **params)[source]

Merges points in the region and inserts the result in a target layer. The params are forwarded to the ‘self.layers’ dictionary.

static add_layer_to_splitter(splitter, region, layer_name, **params)[source]

Add layer to the splitter, which splits the region into different z-levels. The params are forwarded to the ‘self.layers’ dictionary.

Before calling first time, the splitter should be set as empty splitter, which is a list of empty dictionary and empty list, that is [dict(), []].

insert_splitter_layers(splitter, z0)[source]

Inserts the layers in the splitter to the ‘self.layers’ dictionary. Each layer are split into sub-layers by their z-level. Parameter ‘z0’ is the base z-level for layer stack-up.

insert_layers_between_faces(i, opp_i, layer_name, **params)[source]

Helper function to be used to produce indium bumps and TSVs


Create the layers used for simulation export.

Based on any geometry defined on the relevant lithography layers.

This method is called from __init__ after build, and should not be called directly.

Geometry is added to layers created specifically for simulation purposes. The layer numbers, z-levels, thicknesses, materials, and other properties are stored in ‘self.layers’ parameter.

In the simulation-specific layers, all geometry has been merged and converted to simple polygons, that is, polygons without holes.


Returns region of ground grid for the given face id.

produce_waveguide_to_port(location, towards, port_nr, side=None, use_internal_ports=None, waveguide_length=None, term1=0, turn_radius=None, a=None, b=None, over_etching=None, airbridge=False, face=0)[source]

Create a waveguide connection from some location to a port, and add the corresponding port to simulation.ports.

  • location (pya.DPoint) – Point where the waveguide connects to the simulation

  • towards (pya.DPoint) – Point that sets the direction of the waveguide. The waveguide will start from location and go towards towards

  • port_nr (int) – Port index for the simulation engine starting from 1

  • side (str) – Indicate on which edge the port should be located. Ignored for internal ports. Must be one of left, right, top or bottom. If None then direction is inferred from towards.

  • use_internal_ports (bool, optional) – if True, ports will be inside the simulation. If False, ports will be brought out to an edge of the box, determined by side. Defaults to the value of the use_internal_ports parameter

  • waveguide_length (float, optional) – length of the waveguide (μm), used only for internal ports Defaults to the value of the waveguide_length parameter

  • term1 (float, optional) – Termination gap (μm) at location. Default 0

  • turn_radius (float, optional) – Turn radius of the waveguide. Not relevant for internal ports. Defaults to the value of the r parameter

  • a (float, optional) – Center conductor width. Defaults to the value of the a parameter

  • b (float, optional) – Conductor gap width. Defaults to the value of the b parameter

  • over_etching (float, optional) – Expansion of gaps. Defaults to the value of the over_etching parameter

  • airbridge (bool, optional) – if True, an airbridge will be inserted at location. Default False.

  • face – face to place waveguide and port on. Either 0 (default) or 1, for bottom or top face.


Return dictionary with all parameters and their values.

etched_line(p1: klayout.dbcore.DPoint, p2: klayout.dbcore.DPoint)[source]

Return the end points of line segment after extending it at both ends by amount of over_etching. This function must be used when initializing InternalPort.

  • p1 (pya.DPoint) – first end of line segment

  • p2 (pya.DPoint) – second end of line segment


list of extended end points.

Return type

[p1 - d, p2 + d]


Return the port data in dictionary form and add the information of port polygon. Includes following:

  • Items from Port instance

  • polygon: point coordinates of the port polygon

  • signal_edge: point coordinates of the signal edge

  • ground_edge: point coordinates of the ground edge


Return the simulation data in dictionary form. Contains following:

  • gds_file: name of gds file to include geometry layers,

  • units: length unit in simulations, ‘um’,

  • layers: geometry data,

  • material_dict: Dictionary of dielectric materials,

  • box: Boundary box,

  • ports: Port data in dictionary form, see self.get_port_data(),

  • parameters: All Simulation class parameters in dictionary form,


Returns simulation layer numbers in list. Only return layers that are in use.

static delete_instances(cell, name, index=(0,))[source]

Allows for deleting a sub-cell of the top ‘cell’ with a specific ‘name’. The ‘index’ argument can be used to access more than one sub-cell sharing the same ‘name’, but with different appended ‘index’ to the ‘name’.

PCell parameters:

  • box (Shape) - Boundary box, default=(0,0;10000,10000)

  • ground_grid_box (Shape) - Border, default=(0,0;10000,10000)

  • with_grid (Boolean) - Make ground plane grid, default=False

  • name (String) - Name of the simulation, default=Simulation

  • use_ports (Boolean) - Turn off to disable all ports (for debugging), default=True

  • use_internal_ports (Boolean) - Use internal (lumped) ports. The alternative is wave ports., default=True

  • port_size (Double) - The port size can also be set as a list specifying the extensions from the center of the port to left, right, down and up, respectively., default=400.0, unit=µm

  • upper_box_height (Double) - Height of vacuum above top substrate, default=1000.0, unit=µm

  • lower_box_height (Double) - Set > 0 to start face counting from substrate bottom layer., default=0, unit=µm

  • face_stack (List) - The parameter can be set as list of lists to enable multi-face stack-up on substrate surfaces. Set term to empty list to not have metal on the surface., default=['1t1']

  • substrate_height (List) - The value can be scalar or list of scalars. Set as list to use individual substrate heights from bottom to top., default=[550.0, 375.0], unit=[µm]

  • substrate_box (List) - Set as a list of pya.DBox objects to give substrate dimensions individually from bottom to top. If a value in the list is not pya.DBox object, the correspondingsubstrate covers fully the general boundary box., default=[None]

  • substrate_material (List) - Value can be string or list of strings. Use only keywords introduced in material_dict. Set as list to use individual materials from bottom to top., default=['silicon']

  • material_dict (String) - Material property keywords follow Ansys Electromagnetics property names. For example ‘permittivity’, ‘dielectric_loss_tangent’, etc., default={'silicon': {'permittivity': 11.45}}

  • chip_distance (List) - The value can be scalar or list of scalars. Set as list to use individual chip distances from bottom to top., default=[8.0], unit=[µm]

  • ground_metal_height (Double) - Only used in Xsection tool and doesn’t affect the 3D model, default=0.2, unit=µm

  • signal_metal_height (Double) - Only used in Xsection tool and doesn’t affect the 3D model, default=0.2, unit=µm

  • airbridge_height (Double) - Height of airbridges., default=3.4, unit=µm

  • metal_height (List) - Height of metal sheet on each face., default=[0.0], unit=µm

  • dielectric_height (List) - Height of insulator dielectric on each face., default=[0.0], unit=µm

  • dielectric_material (List) - Material of insulator dielectric on each face., default=['silicon'], unit=µm

  • waveguide_length (Double) - Length of waveguide stubs or distance between couplers and waveguide turning point, default=100, unit=µm

  • over_etching (Double) - Expansion of metal gaps (negative to shrink the gaps)., default=0, unit=μm

  • vertical_over_etching (Double) - Vertical over-etching into substrates at gaps., default=0, unit=μm

  • hollow_tsv (Boolean) - Make TSVs hollow with vacuum inside and thin metal boundary., default=False

  • participation_sheet_distance (Double) - Distance to non-model TLS interface sheet., default=0.0, unit=µm

  • participation_sheet_thickness (Double) - Thickness of non-model TLS interface sheet., default=0.0, unit=µm

  • minimum_point_spacing (Double) - Tolerance for merging adjacent points in polygon, default=0.01, unit=µm

  • polygon_tolerance (Double) - Tolerance for merging adjacent polygons in a layer, default=0.004, unit=µm

  • extra_json_data (None) - This field may be used to store ‘virtual’ parameters useful for your simulations, default=None

  • junction_total_length (Double) - Simulation junction total length, default=33, unit=µm

  • a (Double) - Width of center conductor, default=10, unit=μm

  • b (Double) - Width of gap, default=6, unit=μm

  • n (Int) - Number of points on turns, default=64

  • r (Double) - Turn radius, default=100, unit=μm

  • margin (Double) - Margin of the protection layer, default=5, unit=μm

  • face_ids (List) - Chip face IDs list, default=['1t1', '2b1', '1b1', '2t1']

  • display_name (String) - Name displayed in GUI (empty for default), default=

  • protect_opposite_face (Boolean) - Add opposite face protection too, default=False