kqcircuits.simulations.simulation

kqcircuits.simulations.simulation.get_simulation_layer_by_name(layer_name)

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.

kqcircuits.simulations.simulation.to_1d_list(data)

Helper function to cast a scalar or a nested list into a one dimensional list

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

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 and 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.

Parameters:

layout – the layout on which to create the simulation

Keyword Arguments:

**kwargs –

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.

LIBRARY_NAME = None

ports: list[Port]

classmethod from_cell(cell, margin=300, grid_size=1, **kwargs)

Create a Simulation from an existing cell.

Parameters:

• 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

Returns:

Simulation instance

abstract build()

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.

Parameters:

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

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

face(face_id=0)

Returns the face dictionary corresponding to face_id.

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

Parameters:

face_id – name or index of the face, 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.

Parameters:

• 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

Returns:

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.

Parameters:

• cls – Element subclass to be created

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

Returns:

the created cell

get_layer(layer_name, face_id=0)

Returns the specified Layer object.

Parameters:

• 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.

Parameters:

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

• **parameters – Optionally update with other keyword arguments

Returns:

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

face_stack_list_of_lists()

Return self.face_stack forced to be list of lists

static ith_value(list_or_constant, i)

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.

face_z_levels()

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)

Returns a Region containing all geometry from a specified layer

simplified_region(region, expansion=0.0)

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(layer_name, region, z0, z1, **params)

Adds layer parameters into ‘self.layers’ if region is non-empty.

insert_stacked_up_layers(stack, z0)

Produces the layer stack-up and adds the layers into ‘self.layers’. Each layer is split into sub-layers by their z-level.

Parameters:

• stack – list of layers in form of tuples containing (region, layer name, thickness, material)

• z0 – the base z-level for the layer stack-up

insert_layers_between_faces(i, opp_i, layer_name, **params)

Helper function to be used to produce indium bumps and TSVs

create_simulation_layers()

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.

produce_layers(parts)

Finalizes and partitions self.layers.

Metals and non-model objects are left without partitioning. We assume that these do not overlap.

Vacuum or dielectric objects are partitioned if parts is not empty. If these objects overlap, the smaller is subtracted from larger.

Non-model objects are subtracted from vacuum or dielectric objects only if non-model object is mentioned in subtract_keys of vacuum or dielectric object.

ground_grid_region(face_id)

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, airbridge=False, face=0, etch_opposite_face=False, deembed_cross_section=None, **port_kwargs)

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

Parameters:

• 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 waveguide is routed to, either left, right, top or bottom. Ignored when use_internal_ports=True. If None then the edge is inferred from waveguide direction.

• use_internal_ports – If True, a lumped port is placed at the end of straight waveguide segment. If False, the waveguide is brought out to a wave port at the edge of the box, determined by side. If the value is a string ‘at_edge’, then a lumped port will be placed next to the edge. Defaults to the value of the use_internal_ports parameter.

• waveguide_length (float, optional) – length of the straight waveguide starting from location (μm). 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. 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

• 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.

• etch_opposite_face – If true, the metal on opposite face of the waveguide is etched away.

• port_kwargs – keyword arguments passed for port

get_parameters()

Return dictionary with all parameters and their values.

etched_line(p1: DPoint, p2: DPoint)

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.

Parameters:

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

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

Returns:

list of extended end points.

Return type:

[p1 - d, p2 + d]

get_port_data()

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

get_simulation_data()

Return the simulation data in dictionary form. Contains following:

• 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(),

get_layers()

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

get_partition_regions()

Returns partition regions for the simulation instance.

If member function not overriden, will simply return whatever was passed as partition_regions, if any. Can be overriden, for example, to use partition regions defined in kqcircuits.simulations.epr.

static delete_instances(cell, name, index=(0,))

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’.

visualise_region(region: Region, label: str, layer: str = 'visualisation', points: list[DPoint] | DPoint | None = None) → None

Visualises given region in a dedicated layer in the preview geometry file.

Parameters:

• region – pya.Region to visualise

• label – Label of the region, rendered using pya.DText objects

• layer – Name of the KLayout layer to place the visualised region

• points – pya.DPoint or list of DPoints to place as labels to the region. By default places one point at the middle of the region’s boundary box.

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

• fixed_level_stackup (Boolean) - Use fixed level multi-face stack-up, default=True

• 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. The chip distances are measured between the closest layers of the opposing chips., default=[8.0], 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) - Use only keywords introduced in material_dict., 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

• partition_regions (String) - See constructor of the PartitionRegion class for parameter definitions., default=[]

• tls_layer_thickness (List) - Thickness of TLS interface layers (MA, MS, and SA, respectively), default=[0.0], unit=µm

• tls_layer_material (List) - Use only keywords introduced in material_dict. Valid only if tls_sheet_approximation=False., default=['vacuum', 'silicon', 'silicon']

• tls_sheet_approximation (Boolean) - Approximate TLS interface layers as sheets, default=False

• detach_tls_sheets_from_body (Boolean) - Only has an effect when tls_sheet_approximation=True.Setting to False when using `ElmerEPR3DSolution` significantly improves simulation performance, default=True

• 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

• junction_upper_pad_width (Double) - Simulation junction upper metal pad width, default=8, unit=µm

• junction_upper_pad_length (Double) - Simulation junction upper metal pad length, default=13, unit=µm

• junction_lower_pad_width (Double) - Simulation junction lower metal pad width, default=8, unit=µm

• junction_lower_pad_length (Double) - Simulation junction lower metal pad length, default=12, 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) - This applies only on signal carrying elements that typically include some metal between gaps., default=False

• opposing_face_id_groups (List) - Opposing face ID groups (list of lists), default=[['1t1', '2b1']]

• etch_opposite_face (Boolean) - Etch avoidance shaped gap on the opposite face too, default=False

• etch_opposite_face_margin (Double) - Margin of the opposite face etch shape, default=5, unit=μm

• _epr_show (Boolean) - Show geometry related to EPR simulation, if available, default=False

• _epr_cross_section_cut_layer (Layer) - Layer where EPR cross section cuts are placed, default=None

• _epr_cross_section_cut_width (Double) - Width of the EPR cross section cuts when visualised, default=0.0