QDesign

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

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.

Parameters:

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

Attributes

chips

Return a Dict of information regarding chip.

metadata

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

net_info

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.

Returns:

copy of net_info table.

Return type:

pd.DataFrame

qcomponent_latest_assigned_id

Return unique number for each instance.

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

qgeometry

Returns the QGeometryTables (Use for advanced users only)

qnet

Returns the QNet (Use for advanced users only)

renderers

Return a Dict of all the renderers registered within QDesign.

template_options

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

template_renderer_options

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

variables

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

Methods

add_default_data_for_qgeometry_tables(table_name: str, renderer_name: str, column_name: str, column_value) → set

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)

Parameters:

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

Returns:

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:

set

add_dependency(parent: str, child: str)

Add a dependency between one component and another.

Parameters:

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

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

all_component_names_id() → list

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

Returns:

Each tuple has the text name of component and

UNIQUE integer ID for component.

Return type:

list[tuples]

connect_pins(comp1_id: int, pin1_name: str, comp2_id: int, pin2_name: str) → int

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.

Parameters:

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

Returns:

Unique net_id of connection used in the netlist.

Return type:

int

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

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.

Parameters:

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

Returns:

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:

Dict

copy_qcomponent(original_qcomponent: QComponent, new_component_name: str, options_superimpose: dict = {}) → QComponent | None

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

Parameters:

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

Returns:

None if not copied, otherwise, a QComponent instance.

Return type:

union[‘QComponent’, None]

delete_all_components()

Clear all components in the design dictionary.

Also clears all pins and netlist.

delete_all_pins() → QNet

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

Returns:

QNet with all pins removed

Return type:

QNet

delete_component(component_name: str, force: bool = False) → bool

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.

Parameters:

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

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

Returns:

Is there no such component

Return type:

bool

get_chip_layer(chip_name: str = 'main') → int

Return the chip layer number for the ground plane.

Parameters:

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

Returns:

Layer of ground plane

Return type:

int

get_chip_size(chip_name: str = 'main') → dict

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

Parameters:

chip_name (str) – Name of the chip.

Returns:

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

Return type:

dict

get_chip_z(chip_name: str = 'main') → str

Utility function to return the z value of a chip.

Parameters:

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

Returns:

String representation of the chip height.

Return type:

str

get_design_name() → str

Get the name of the design from the metadata.

Returns:

Name of design

Return type:

str

get_list_of_tables_in_metadata(a_metadata: dict) → list

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

Parameters:

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

Returns:

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

Return type:

list

get_units()

Gets the units of the design.

Returns:

units

Return type:

str

classmethod load_design(path: str)

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

Parameters:

path (str) – Path to saved Metal design.

Returns:

Loaded metal design.

Return type:

QDesign

parse_options(params: dict, param_names: str) → dict

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

Parameters:

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

Returns:

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

Return type:

dict

parse_value(value: Any | List | Dict | Iterable) → Any

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

Parameters:

• value (str) – String to parse or

• variable_dict (dict) – dict pointer of variables

Returns:

Parsed value

Return type:

str, float, list, tuple, or ast eval

Handled Inputs:

Strings:

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

Dictionaries:

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.

Numbers:

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

Arithemetic:

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

Examples

See the docstring for this module.

qiskit_metal.toolbox_metal.parsing

rebuild()

Remakes all components with their current parameters.

remove_dependency(parent: str, child: str)

Remove a dependency between one component and another.

Parameters:

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

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.

Parameters:

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

• new_component_name (str) – New name

Returns:

Results

Return type:

int

Results:

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)

Renames a variable in the variables dictionary. Preserves order.

Parameters:

• old_key (str) – Previous variable name

• new_key (str) – New variable name

save_design(path: str | None = None)

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

Parameters:

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

Returns:

True if successful; False if failure

Return type:

bool

set_design_name(name: str)

Set the name of the design in the metadata.

Parameters:

name (str) – Name of design

to_python_script(thin=True, printout: bool = False)

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

Returns:

Python script for current chip

Return type:

str

update_component(component_name: str, dependencies: bool = True)

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

Parameters:

• component_name (str) – Component name to update

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

update_metadata(new_metadata: dict)

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.

Parameters:

new_metadata (dict) – New metadatadata dict to update