class QDesign(metadata: dict | None = None, overwrite_enabled: bool = False, enable_renderers: bool = True)[source]#

QDesign is the base class for Qiskit Metal Designs.

A design is the most top-level object in all of Qiskit Metal.

Create a new Metal QDesign.

  • metadata (Dict) – Dictionary of metadata. Defaults to None.

  • overwrite_enabled (bool) –

    When True - If the string name, used for component, already

    exists in the design, the existing component will be deleted from design, and new component will be generated with the same name and newly generated component_id, and then added to design.

    When False - If the string name, used for component, already

    exists in the design, the existing component will be kept in the design, and current component will not be generated, nor will be added to the design. The ‘NameInUse’ will be returned during component generation.

    Either True or False - If string name, used for component, is NOT

    being used in the design, a component will be generated and added to design using the name.

  • enable_renderers – Enable the renderers during the init() of design. The list in config.renderers_to_load() to determine which renderers to enable.



Return a Dict of information regarding chip.


Return the metadata Dict object that keeps track of all metadata in the design.

Provides a copy of net_info table which holds all the connections,

of pins, within a design. An advanced user can use methods within the class of design._qnet. Also, an advanced user can also directly edit the table at design._qnet._net_info.


copy of net_info table.

Return type:



Return unique number for each instance.

For user of the design class to know the lastest id assigned to QComponent.


Returns the QGeometryTables (Use for advanced users only)


Returns the QNet (Use for advanced users only)


Return a Dict of all the renderers registered within QDesign.


Return default_options dictionary, which contain default options used in creating Metal component, and in calling other drawing and key functions.


Return default_renderer_options dictionary, which contain default options used in creating Metal renderer.


Return the Dict object that keeps track of all variables in the design.


add_default_data_for_qgeometry_tables(table_name: str, renderer_name: str, column_name: str, column_value) set[source]#

Populate the dict (self.renderer_defaults_by_table) which will hold the data until a component’s get_template_options(design) is executed.

Note that get_template_options(design) will populate the columns of QGeometry table i.e. path, junction, poly etc.

Example of data format is: self.renderer_defaults_by_table[table_name][renderer_name][column_name] = column_value

The type for default value placed in a table column is determined by populate_element_extentions() on line: cls.element_extensions[table][col_name] = type(col_value) in renderer_base.py.

Dict layout and examples within parenthesis:

key: Only if need to add data to components, for each type of table (path, poly, or junction). value: Dict which has

keys: render_name (gds), value: Dict which has

keys: ‘filename’, value: (path/filename)

keys: render_name (hfss), value: Dict which has

keys: ‘inductance’, value: (inductance_value)

  • table_name (str) – Table used within QGeometry tables i.e. path, poly, junction.

  • renderer_name (str) – The name of software to export QDesign, i.e. gds, Ansys.

  • column_name (str) – The column name within the table, i.e. filename, inductance.

  • column_value (Object) – The type can vary based on column. The data is placed under column_name.


Each integer in the set has different meanings.
  • 1 - added key for table_name

  • 2 - added key for renderer_name

  • 3 - added new key for column_name

  • 4 - since column_name already existed, column_value replaced previous column_value

  • 5 - Column value added

  • 6 - Expected str, got something else.

Return type:


add_dependency(parent: str, child: str)[source]#

Add a dependency between one component and another.

  • parent (str) – The component on which the child depends.

  • child (str) – The child cannot live without the parent.

all_component_names_id() list[source]#

Get the text names and corresponding unique ID of each component within this design.


Each tuple has the text name of component and

UNIQUE integer ID for component.

Return type:


connect_pins(comp1_id: int, pin1_name: str, comp2_id: int, pin2_name: str) int[source]#

Will generate an unique net_id and placed in a net_info table. Update the components.pin_name with the net_id.

Component’s pin will know if pin is connected to another component, if there is a non-zero net_id.

  • comp1_id (int) – Unique id of component used for pin1_name.

  • pin1_name (str) – Name of pin in comp1_id.

  • comp2_id (int) – Unique id of component used for pin2_name.

  • pin2_name (str) – Name of pin in comp2_id.


Unique net_id of connection used in the netlist.

Return type:


Note: If not added to netlist, the net_id will be 0 (zero).

copy_multiple_qcomponents(original_qcomponents: list, new_component_names: list, all_options_superimpose: list = []) Dict[source]#

The lists in the arguments are all used in parallel. If the length of original_qcomponents and new_component_names are not the same, no copies will be made and an empty Dict will be returned. The length of all_options_superimposes needs to be either empty or exactly the length of original_qcomponents, otherwise, an empty dict will be returned.

  • original_qcomponents (list) – Must be a list of original QComponents.

  • new_component_names (list) – Must be a list of QComponent names.

  • all_options_superimpose (list, optional) – Must be list of dicts with options to superimpose on options from original_qcomponents. The list can be of both populated and empty dicts. Defaults to empty list().


Number of keys will be the same length of original_qcomponent.

Each key will be the new_component_name. Each value will be either a QComponent or None. If the copy did not happen, the value will be None, and the key will extracted from new_componet_names.

Return type:


copy_qcomponent(original_qcomponent: QComponent, new_component_name: str, options_superimpose: dict = {}) QComponent | None[source]#

Copy a qcomponent in QDesign and add it to QDesign._components using options_overwrite.

  • original_class (QComponent) – The QComponent to copy.

  • new_component_name (str) – The name should not already be in QDesign, if it is, the copy fill fail.

  • options_superimpose (dict) – Can use different options for copied QComponent. Will start with the options in original QComponent, and then superimpose with options_superimpose. An example would be x and y locations.


None if not copied, otherwise, a QComponent instance.

Return type:

union[‘QComponent’, None]


Clear all components in the design dictionary.

Also clears all pins and netlist.

delete_all_pins() QNet[source]#

Clear all pins in the net_Info and update the pins in components.


QNet with all pins removed

Return type:


delete_component(component_name: str, force: bool = False) bool[source]#

Deletes component and pins attached to said component.

If no component by that name is present, then just return True If component has dependencices return false and do not delete, unless force=True.

  • component_name (str) – Name of component to delete.

  • force (bool) – Force delete component even if it has children. Defaults to False.


Is there no such component

Return type:


get_chip_layer(chip_name: str = 'main') int[source]#

Return the chip layer number for the ground plane.


chip_name (str, optional) – User can overwrite name of chip. Defaults to ‘main’.


Layer of ground plane

Return type:


get_chip_size(chip_name: str = 'main') dict[source]#

Utility function to get a dictionary containing chip dimensions (size and center).


chip_name (str) – Name of the chip.


Dictionary of chip dimensions, including central coordinates and widths along x, y, and z axes.

Return type:


get_chip_z(chip_name: str = 'main') str[source]#

Utility function to return the z value of a chip.


chip_name (str) – Returns the size of the given chip. Defaults to ‘main’.


String representation of the chip height.

Return type:


get_design_name() str[source]#

Get the name of the design from the metadata.


Name of design

Return type:


get_list_of_tables_in_metadata(a_metadata: dict) list[source]#

Look at the metadata dict to get list of tables the component uses.


a_metadata (dict) – Use dict from gather_all_children for metadata.


List of tables, the component-developer, denoted as being used in metadata.

Return type:



Gets the units of the design.



Return type:


classmethod load_design(path: str)[source]#

Load a Metal design from a saved Metal file. Will also update default dictionaries. (Class method).


path (str) – Path to saved Metal design.


Loaded metal design.

Return type:


parse_options(params: dict, param_names: str) dict[source]#

Extra utility function that can call parse_value on individual options. Use self.parse_value to parse only some options from a params dictionary.

  • params (dict) – Input dict to pull form

  • param_names (str) – Keys of dictionary to parse and return as a dictionary. Example value: ‘x,y,z,cpw_width’


Dictionary of the keys contained in param_names with values that are parsed.

Return type:


parse_value(value: Any | List | Dict | Iterable) Any[source]#

Main parsing function. Parse a string, mappable (dict, Dict), iterable (list, tuple) to account for units conversion, some basic arithmetic, and design variables.

  • value (str) – String to parse or

  • variable_dict (dict) – dict pointer of variables


Parsed value

Return type:

str, float, list, tuple, or ast eval

Handled Inputs:

Strings of numbers, numbers with units; e.g., ‘1’, ‘1nm’, ‘1 um’

Converts to int or float. Some basic arithmetic is possible, see below.

Strings of variables ‘variable1’.

Variable interpertation will use string method isidentifier ‘variable1’.isidentifier()


Returns ordered Dict with same key-value mappings, where the values have been subjected to parse_value.

Iterables(list, tuple, …):

Returns same kind and calls itself parse_value on each element.


Returns the number as is. Int to int, etc.


Some basic arithemetic can be handled as well, such as ‘-2 * 1e5 nm’ will yield float(-0.2) when the default units are set to mm.

Default units:

User units can be set in the design. The design will set config.DEFAULT.units


See the docstring for this module.



Remakes all components with their current parameters.

remove_dependency(parent: str, child: str)[source]#

Remove a dependency between one component and another.

  • parent (str) – The component on which the child depends.

  • child (str) – The child cannot live without the parent.

rename_component(component_id: int, new_component_name: str)[source]#

Rename component. The component_id is expected. However, if user passes a string for component_id, the method assumes the component_name was passed. Then will look for the id using the component_name.

  • component_id (int) – id of component within design, can pass a string for component_name

  • new_component_name (str) – New name



Return type:



1: True name is changed. (True)

-1: Failed, new component name exists.

-2: Failed, invalid new name; it is already being used by another component.

-3: Failed, component_id does not exist.

rename_variable(old_key: str, new_key: str)[source]#

Renames a variable in the variables dictionary. Preserves order.

  • old_key (str) – Previous variable name

  • new_key (str) – New variable name

save_design(path: str | None = None)[source]#

Save the metal design to a Metal file. If no path is given, then tried to use self.save_path if it is set.


path (str) – Path to save the design to. Defaults to None.


True if successful; False if failure

Return type:


set_design_name(name: str)[source]#

Set the name of the design in the metadata.


name (str) – Name of design

to_python_script(thin=True, printout: bool = False)[source]#

Generates a python script from current chip :param printout: Whether to print the script :type printout: bool


Python script for current chip

Return type:


update_component(component_name: str, dependencies: bool = True)[source]#

Update the component and any dependencies it may have. Mediator type function to update all children.

  • component_name (str) – Component name to update

  • dependencies (bool) – True to update all dependencies. Defaults to True.

update_metadata(new_metadata: dict)[source]#

Update the metadata dictionary of the design with a new metadata dictionary. This will overwrite only the new keys that you pass in. All other keys will be unaffected.


new_metadata (dict) – New metadatadata dict to update