Component

Component(name='', technology=None)

Component object.

Args

• name (str): Name of the component.
• technology (Technology | None): Technology specification for this component.

Methods

Method	Description
activate_model	Set model as active for S matrix computation.
add	Add structures, labels, and references to this component.
add_model	Add a model to this component.
add_port	Add a port to this component.
add_reference	Add a reference to this component.
add_reference_ports	Add a reference to this component.
add_terminal	Add a terminal to this component.
add_virtual_connection	Adds a virtual connection between references in this component.
add_virtual_connection_by_instance	Adds a virtual connection between references in this component.
add_virtual_net	Declare sub-reference terminals as one net.
bounds	Calculate the component bounds.
build_mask	Compute the component’s mask based on a mask specification.
center	Calculate the component center.
convex_hull	Calculate the convex hull of this component.
copy	Create a copy of this component.
dependencies	Return a list of components recursively present in this component’s
detect_dependency_cycle	Check wheter this component includes a dependency cycle.
detect_ports	Try to detect ports in this components base on its structures.
disconnected_reference_ports	Get all ports from references that are not connected.
extract_connectivity	Extract physical electrical connectivity from layout geometry.
extrude	Extrude this component according to its technology specification.
filter_label_layers	Remove labels from the component based on their layer.
filter_layers	Remove structures from the component based on their layer.
flatten	Replace component references with their corresponding contents.
get_instance_maps	Compute mappings between references and instace indices.
get_labels	Get all labels in the component and its references.
get_netlist	Return a netlist representation of this component.
get_structures	Get all structures in the component and its references.
invalid_virtual_connections	Return invalid virtual connections in this component.
label_count	Return the number labels in this component, excluding dependencies.
layers	Return the layers used in this component.
query	Query ports and terminals from the component or its references.
remap_label_layers	Reassign the layers in this component’s labels.
remap_layers	Reassign the layers in this component’s structures.
remove	Remove structures, labels, and references from this component.
remove_model	Remove a model from this component.
remove_port	Remove a port from this component.
remove_terminal	Remove a terminal from this component.
remove_virtual_connection	Remove a virtual connection to a reference in this component.
remove_virtual_connection_by_instance	Remove a virtual connection to a reference in this component.
remove_virtual_net	Remove every declared net containing a terminal endpoint.
remove_virtual_net_by_instance	Remove every declared net containing an instance terminal.
remove_virtual_net_member	Detach one terminal from the nets holding it.
rename_model	Rename the model if model exists in the component.
rename_port	Rename port in the component.
rename_terminal	Rename terminal in the component.
replace_technology	Replace technology for the component and its dependencies.
s_matrix	Compute the S matrix for this component using its active model.
select_active_model	Return the electrical or optical active model from this component.
select_ports	Return electrical or optical ports from this component.
set_bounds	Clip the contents of this components to the given rectangular bounds.
setup_time_stepper	Initialize a time stepper for this component using its active model.
size	Calculate the component size.
slice_profile	Get the slice profile of all structures in this component.
structure_count	Return the number structures in this component, excluding dependencies.
tree_view	Create a tree view of this component and its dependencies.
update	Update this component if it was created as a parametric component.
write_gds	Export this component as a GDSII file.
write_oas	Export this component as an OASIS file.

activate_model

activate_model(self, model_name, classification=None)

Set model as active for S matrix computation.

Args

• model_name (str): Name of the model to set as active.
• classification (Literal[“optical”, “electrical”] | None): Frequency range for which to activate the model. If None, activates the model for both frequency ranges.

Returns

Model: Activated model.

add

add(self, *args)

Add structures, labels, and references to this component.

Args

• *args (str | tuple[int, int] | Polygon | Rectangle | Circle | Path | Label | Reference | Component): Objects to be added. In order to add structure(s) to a specific layer, pass the layer name or tuple before de structure(s) (see example below).

Returns

Component: This component.

Example

>>> rect1 = pf.Rectangle((0, 0), (2, 1))
>>> rect2 = pf.Rectangle((1, 0), (3, 1))
>>> rect3 = pf.Rectangle((2, 0), (4, 1))
>>> component = pf.Component("MAIN")
>>> # Add rect1 and rect2 to layer (1, 0), and rect3 to "SLAB"
>>> component.add((1, 0), rect1, rect2, "SLAB", rect3)
Component(...)

add_model

add_model(self, model, model_name=None, set_active=True)

Add a model to this component.

Args

• model (Model | Sequence[Model]): Model to be added. A sequence of models can be passed to add all simultaneously.
• model_name (str | None): Model name. If a model with this name already exists, it will be replaced. If a list of models is used, the name of each model is suffixed with a number from 0 to list size - 1.
• set_active (bool | Literal[“optical”, “electrical”]): Flag used to set the model as active. If "optical" or "electrical", set only for the respective frequency range.

Returns

str | list[str]: The model name(s).

add_port

add_port(self, port, port_name=None)

Add a port to this component.

Args

• port (Port | FiberPort | GaussianPort | dict[str, Port | FiberPort | GaussianPort] | Sequence[Port | FiberPort | GaussianPort]): Port to be added. A sequence or dictionary of ports can be passed and all will be added simulataneously.
• port_name (str | None): Port name. If a port with this name already exists, it will be replaced. If a sequence of ports is used, the name of each port is suffixed with a number from 0 to the list size - 1. This argument has no effect if a dictionary is used.

Returns

str | list[str]: The port name(s).

add_reference

add_reference(self, reference)

Add a reference to this component.

Args

• reference (Reference | Component): Referece or component to add.

Returns

Reference: Reference added.

add_reference_ports

add_reference_ports(self, include_dependencies=False, add_model=None)

Add a reference to this component.

Args

• include_dependencies (bool): If set, add reference ports to dependencies before operating in this component.
• add_model (Model | None): If given, this model is added to the component if it doesn’t have an active model (copies are added to dependencies without active models, if include_dependencies is True).

Returns

list[str]: Names of the ports added to this component.

add_terminal

add_terminal(
    self,
    terminal,
    terminal_name=None,
    add_structure=False,
    structure_layer=None,
)

Add a terminal to this component.

Args

• terminal (Terminal | dict[str, Terminal] | Sequence[Terminal]): Terminal to be added. A sequence or dictionary of terminals can be passed to add all simulataneously.
• terminal_name (str | None): Terminal name. If a terminal with this name already exists, it will be replaced. If a sequence of terminals is used, the name of each terminal is suffixed with a number from 0 to the list size - 1. This argument has no effect if a dictionary is used.
• add_structure (bool): If True, the terminal template is also added to the component as real layout geometry.
• structure_layer (str | tuple[int, int] | None): Layer to add the terminal structure. If None, uses Terminal.routing_layer.

Returns

str | list[str]: The terminal name(s).

add_virtual_connection

add_virtual_connection(
    self,
    reference0,
    port_name0,
    reference1,
    port_name1,
    repetition_index0=0,
    repetition_index1=0,
)

Adds a virtual connection between references in this component.

Virtual connections can be used to force a connection between references that are physically disconnected with respect to their port positions. These connections will be included in the generated netlist for the component and used, for example, in a circuit model.

Args

• reference0 (Reference): First reference to connect.
• port_name0 (str): Port name to connect from the first reference.
• reference1 (Reference): Second reference to connect.
• port_name1 (str): Port name to connect from the second reference.
• repetition_index0 (int): If the first reference contains repetitions, select from the list using this index. It must be 0 if it has no repetitions.
• repetition_index1 (int): If the second reference contains repetitions, select from the list using this index. It must be 0 if it has no repetitions.

Returns

Component: This component.

Note

Different from Reference.connect, this method does not move or rotate the references.

The connection is not validated when created, only when used, i.e. it is possible to create connections before creating the required ports or repetition, or even adding the reference to the component. However, if one of the references is deleted because it’s not being used, the connection will be automatically removed.

add_virtual_connection_by_instance

add_virtual_connection_by_instance(
    self, instance_index0, port_name0, instance_index1, port_name1
)

Adds a virtual connection between references in this component.

Virtual connections can be used to force a connection between references that are physically disconnected with respect to their port positions.

Args

• instance_index0 (int): Index to the first instance to connect from the instances list in this component’s Component.get_netlist.
• port_name0 (str): Port name to connect from the first reference.
• instance_index1 (int): Index to the second instance to connect from the instances list in this component’s Component.get_netlist.
• port_name1 (str): Port name to connect from the second reference.

Returns

Component: This component.

Note

Different from Reference.connect, this method does not move or rotate the references.

The connection is not validated when created, only when used, i.e. it is possible to create connections before creating the required ports. However, if one of the references is deleted because it’s not being used, the connection will be automatically removed.

add_virtual_net

add_virtual_net(self, terminals)

Declare sub-reference terminals as one net.

Args

• terminals: Sequence of (reference, terminal) or (reference, terminal, repetition_index) tuples, or a plain string naming a component boundary terminal, which is the same as a member with a None reference. Several boundary terminals may name one net; each becomes a node of its own, shorted to the others. Each terminal is a terminal name, or a (port_name, terminal_name) tuple for a terminal belonging to a port, using the same form reported by Component.get_netlist. A port terminal is the component’s wave interface: it is drawn and reported, but MNA assembly never treats it as a node.

Returns

This component.

bounds

bounds(self, include_ports=True, include_labels=True, layers=None)

Calculate the component bounds.

Args

• include_ports (bool): If set, include ports and terminals.
• include_labels (bool): If set, include labels.
• layers (Iterable[str | tuple[int, int]] | None): If set, only include structures or labels on the specified layers.

Returns

tuple[ndarray, ndarray]: The lower-left and upper-right corners of the bounding box of the component: ((min_x, min_y), (max_x, max_y)).

build_mask

build_mask(self, mask_spec, heal=False)

Compute the component’s mask based on a mask specification.

Args

• mask_spec (MaskSpec | str | tuple[int, int]): Mask specification or single layer.
• heal (bool | float): If set, a healing step is applied to the created masks that eliminates geometrical features below the current tolerance. This argument can also be set to a number that specifies the feature limit directly.

Returns

list[Polygon]: Polygons that make up the mask.

center

center(self, include_ports=True, include_labels=True)

Calculate the component center.

Args

• include_ports (bool): If set, include ports and terminals.
• include_labels (bool): If set, include labels.

Returns

ndarray: The component center.

convex_hull

convex_hull(self, include_labels=True, layers=None)

Calculate the convex hull of this component.

Args

• include_labels (bool): If set, include labels.
• layers (Iterable[str | tuple[int, int]] | None): If set, only include structures or labels on the specified layers.

Returns

ndarray: Vertices of the convex hull.

copy

copy(self, deep=False, copy_technology=False)

Create a copy of this component.

Args

• deep (bool): If set, creates copies of all subcomponents. Otherwise, all subcomponents are re-used.
• copy_technology (bool): If set, a copy of the component technology is used, otherwise the same technology instance.

Returns

Component: New copy.

dependencies

dependencies(self)

Return a list of components recursively present in this component’s references.

Returns

list[Component]: List of components.

detect_dependency_cycle

detect_dependency_cycle(self)

Check wheter this component includes a dependency cycle.

Returns

Component | None: First component found that creates a cycle.

detect_ports

detect_ports(
    self,
    specs=None,
    bounds=None,
    skip_internal_connections=True,
    on_boundary=None,
    boundary_margin=0,
    minimal_turn_angle=10,
)

Try to detect ports in this components base on its structures.

Args

• specs (Iterable[PortSpec] | None): PortSpec instances or names to be uses as base for searching. If set to None, all specifications from the component technology are used.
• bounds (tuple[tuple[float]] | ndarray | None): Limit the search for ports within these bounds, specified as ((x_min, y_min), (x_max, y_max)).
• skip_internal_connections (bool): If set, internal ports that are connected (overlapping ports in opposite directions, such as those in adjacent path sections) are removed from the results.
• on_boundary (Literal[“xy”, “x”, “+x”, “-x”, “y”, “+y”, “-y”] | None): Limit the search to ports at the devices boundaries.
• boundary_margin (float): When searching on boundaries, include the region within this margin from the component bounds.
• minimal_turn_angle (float): Minimal turning angle (in degrees) between adjacent polygon edges to consider the edges as candidates for port.

Returns

list[Port]: List of detected ports.

Note

The returned ports are not automatically added to the component.

See Also

Ports guide

disconnected_reference_ports

disconnected_reference_ports(self)

Get all ports from references that are not connected.

Reference ports are connected when they participate in a connection or virtual connection between references or when they overlap any existing component ports.

Returns

list[Port | FiberPort | GaussianPort]: Disconnected ports.

extract_connectivity

extract_connectivity(
    *,
    conductive_layers=None,
    connected_layers=None,
    device_layers=None,
    excluded_layers=(),
    excluded_layer_connections=(),
    connect_by_abutment=True,
    black_boxes=(),
    conductive_components=(),
)

Extract physical electrical connectivity from layout geometry.

Args

• conductive_layers (Iterable[str | tuple[int, int]] | None): Conductive routing layers. None uses the layers whose root technology specifications set conductive=True, plus every layer used in the selected connected layer pairs; a warning is emitted if none are declared, or if a pair uses an undeclared layer. An empty iterable disables extraction.
• connected_layers (Iterable[tuple[Layer, Layer]] | None): Cross-layer connection rules, replacing the root technology’s connected_layers when given. An empty iterable disables cross-layer connections.
• device_layers (Iterable[str | tuple[int, int]] | None): Device recognition layers, replacing the layers whose root technology specifications set device_marker=True when given. A marker drawn on one of these removes the conductor beneath it, so a device drawn inline does not short its own terminals, while a terminal keeps the conductor under it. It cuts only: no device is created.
• excluded_layers (Iterable[str | tuple[int, int]]): Layers to remove from the effective conductive set.
• excluded_layer_connections (Iterable[tuple[Layer, Layer]]): Selected connected layer pairs to disable. A layer cannot be paired with itself.
• connect_by_abutment (bool): Whether cross-layer geometry that only abuts, sharing an edge or a corner, connects. Same-layer geometry always connects on any contact.
• black_boxes (Iterable[Component | str]): Additional components, by object or by name, whose internal geometry is left out of extraction. A component whose active electrical model describes its terminals, such as a lumped element or a circuit model with a port map, is left out automatically: the model already accounts for the conduction inside it. Either way the component’s own terminals stay conductive, so whatever abuts them still connects.
• conductive_components (Iterable[Component | str]): Components, by object or by name, whose geometry is extracted even though they carry such a model.

Returns

list[list[tuple[Reference | None, str | tuple[str, str], int]]]: Physical N-way nets. Each member is a reference, a terminal, and the reference’s repetition index. None denotes a boundary terminal on this component, always with repetition index 0. A terminal owned by a port is reported as a (port_name, terminal_name) tuple.

Note

A net with a single member is a dangling terminal — alone on its conductor island, or over no conductor at all — reported for LVS and routing and warned about unless it is port-derived. A terminal whose layer is outside the effective conductive set is not reported, and a warning names it.

extrude

extrude(
    self,
    port_extension=0,
    heal=False,
    extrusion_tolerance=0,
    classification='optical',
    used_extrusions=None,
)

Extrude this component according to its technology specification.

Args

• port_extension (float): Extension length for ports marked as extended (Port.extended).
• heal (bool | float): If set, a healing step is applied to the created masks that eliminates geometrical features below the current tolerance. This argument can also be set to a number that specifies the feature limit directly.
• extrusion_tolerance (float): Minimal out-of-plane interval used to refine topological changes and sidewall slope mismatches. Slope mismatches within this interval are accepted. Meshing failures fall back to an orthogonal midpoint profile with a warning. A value of 0 or less defaults to config.tolerance.
• classification (Literal[“optical”, “electrical”]): Frequency classification indicating which type of medium to use.
• used_extrusions (list | None): If this argument is set to a list, all extrusion specifications that are effectively used will be appended to it.

Returns

list[Polyhedron | Extruded | ConstructiveSolid]: List of 3D structures.

filter_label_layers

filter_label_layers(self, layers, keep, include_dependencies=False)

Remove labels from the component based on their layer.

Args

• layers (Iterable[str | tuple[int, int]]): Layers to keep or remove.
• keep (bool): Boolean flag indicating whether the layers represent the layers that should be removed (False) or kept (True).
• include_dependencies (bool): If set, filter all component dependencies too.

Returns

Component: This component.

filter_layers

filter_layers(self, layers, keep, include_dependencies=False)

Remove structures from the component based on their layer.

Args

• layers (Iterable[str | tuple[int, int]]): Layers to keep or remove.
• keep (bool): Boolean flag indicating whether the layers represent the layers that should be removed (False) or kept (True).
• include_dependencies (bool): If set, filter all component dependencies too.

Returns

Component: This component.

Example

>>> component.filter_layers([(1, 0), (3, 0)], True)  # doctest: +SKIP

flatten

flatten(self)

Replace component references with their corresponding contents.

All references in this component are removed and, in their place, new structures and labels are added that recreate the removed components. After flattening, the component is left with no dependencies.

Returns

Component: This component.

get_instance_maps

get_instance_maps(self)

Compute mappings between references and instace indices.

Returns

tuple[dict[tuple[int, int], int], list[tuple[int, int]]]: Dictionary mapping from (reference_index, repetition_index) to instance_index and a list mapping from instance_index to (reference_index, repetition_index).

get_labels

get_labels(self, layer=None, depth=-1, skip_components=())

Get all labels in the component and its references.

Args

• layer (str | tuple[int, int] | None): If specified, only labels in this layer are returned.
• depth (int): If not negative, limits the depth of search into references.
• skip_components (Iterable[str | Component]): Component instances or names whose labels should not be returned.

Returns

list[Label] | dict[tuple[int, int], Label]: List of labels when layer is set, or a dictionary of labels indexed by layer otherwise.

Note

Components are skipped by name. If multiple components have the same name, all will be skipped together.

get_netlist

get_netlist(
    self,
    include_virtual_connections=True,
    *,
    conductive_layers=None,
    connected_layers=None,
    device_layers=None,
    excluded_layers=(),
    excluded_layer_connections=(),
    connect_by_abutment=True,
    black_boxes=(),
    conductive_components=(),
    suppress_warnings=False,
)

Return a netlist representation of this component.

The netlist is a dictionary containing these entries:

• ‘instances’: list of Reference objects that participate in the netlist circuit. They are guaranteed to have no repetitions.

• ‘ports’: dictionary of the netlist input and output port names indexed by instance port. An instance port is a tuple with 3 elements: an integer index into the ‘instances’ list, a string with the instance port name, and the number of modes supported by that port.

• ‘terminals’: dictionary of the netlist input and output terminal names indexed by instance terminal. An instance terminal is a tuple with 2 elements: an integer index into the ‘instances’ list, and either (a) a string with the instance terminal name, or (b) a tuple with the instance port name and the port terminal name, depending on whether the terminal comes from an instance port or not.

• ‘connections’: list of tuples with 2 instance ports that are connected within the netlist. The numbers of modes in connected ports are guaranteed to be the same.

• ‘nets’: list of physical N-way nets. A net with a single member is a dangling terminal --- alone on its conductor island, or over no conductor at all --- reported for LVS and routing. Each member is an instance terminal (instance_index, terminal_name); a None instance index denotes the component’s own boundary terminal. Hierarchical conductor geometry joins terminals according to the selected routing layers and selected connected layer pairs. A terminal owned by a port is named (port_name, terminal_name) and listed only while its port carries no wave connectivity; MNA assembly never treats it as a node.

• ‘virtual nets’: list of declared N-way nets, using the same member format as ‘nets’.

• ‘virtual connections’: list of tuples with 2 instance ports that are virtually connected within the netlist. The numbers of modes in connected ports are guaranteed to be the same.

• ‘butt couplings’: list of tuples with 2 instance ports that are connected within the netlist, but have different profiles. The numbers of modes in butt-coupled ports can be different.

Args

• include_virtual_connections (bool): Whether to include or ignore virtual port and nets in the component. It can be turned off to limit checking only layout-based connections.
• conductive_layers (Iterable[str | tuple[int, int]] | None): Conductive routing layers. None uses the layers whose root technology specifications set conductive=True, plus every layer used in the selected connected layer pairs.
• connected_layers (Iterable[tuple[Layer, Layer]] | None): Cross-layer connection rules, replacing the root technology’s connected_layers when given. An empty iterable disables cross-layer connections.
• device_layers (Iterable[str | tuple[int, int]] | None): Device recognition layers, replacing the layers whose root technology specifications set device_marker=True when given. A marker drawn on one of these removes the conductor beneath it, so a device drawn inline does not short its own terminals, while a terminal keeps the conductor under it. It cuts only: no device is created.
• excluded_layers (Iterable[str | tuple[int, int]]): Conductive layers to exclude.
• excluded_layer_connections (Iterable[tuple[Layer, Layer]]): Selected connected layer pairs to exclude. A layer cannot be paired with itself.
• connect_by_abutment (bool): Whether cross-layer geometry that only abuts, sharing an edge or a corner, connects.
• black_boxes (Iterable[Component | str]): Additional components, by object or by name, whose internal geometry is left out of extraction. A component whose active electrical model describes its terminals is left out automatically, with its own terminal staying conductive.
• conductive_components (Iterable[Component | str]): Components whose geometry is extracted even though they carry such a model.
• suppress_warnings (bool): Silence warnings about port and terminal connections, including dangling terminals. A terminal joined to another only by a declared net is not dangling.

Returns

dict[str, object]: Netlist as a dictionary with keys ‘instances’, ‘ports’, ‘terminals’, ‘connections’, ‘nets’, ‘virtual nets’, ‘butt couplings’, and ‘virtual connections’.

get_structures

get_structures(self, layer=None, depth=-1, skip_components=())

Get all structures in the component and its references.

Args

• layer (str | tuple[int, int] | None): If specified, only structures in this layer are returned.
• depth (int): If not negative, limits the depth of search into references.
• skip_components (Iterable[str | Component]): Component instances or names whose structures should not be returned.

Returns

list[Rectangle | Circle | Polygon | Path] | dict[tuple[int, int], Rectangle | Circle | Polygon | Path]: List of structures when layer is set, or a dictionary of structures indexed by layer otherwise.

Note

Components are skipped by name. If multiple components have the same name, all will be skipped together.

invalid_virtual_connections

invalid_virtual_connections(self)

Return invalid virtual connections in this component.

Returns

list[tuple[tuple[Reference, str, int], tuple[Reference, str, int]]]: List of invalid connections. Each endpoint is a reference, its port name, and the reference’s repetition index.

label_count

label_count(self)

Return the number labels in this component, excluding dependencies.

Returns

int: Number of labels in the component.

layers

layers(
    self,
    include_dependencies=False,
    include_structures=True,
    include_labels=True,
)

Return the layers used in this component.

Args

• include_dependencies (bool): If set, the return list also includes layers used in dependencies.
• include_structures (bool): Whether to include structure layers or not.
• include_labels (bool): Whether to include label layers or not.

Returns

set[tuple[int, int]]: Layer set.

query

query(self, *args)

Query ports and terminals from the component or its references.

Args

• *args (str | int | None): Strings, integers or None representing a reference specification ending with a port/terminal specification (see below for further information).

Returns

Port | FiberPort | GaussianPort | Terminal | list[Port | FiberPort | GaussianPort | Terminal]: Selected ports and terminals. If the resulting selection contains only a single element, the element itself is returned.

The selection happens by matching sub-component, ports and terminal names. Each string argument is interpreted as a regular expression (using ECMA-262 grammar) to be matched against a sub-component name. The first sub-component that matches is selected and the selection continues with the next argument within that subcomponent. The last string is matched against port and terminal names within the final component.

An integer argument following a string limits the matching to the index represented by the integer. A negative value (default) selects all matches.

A value of None indicates that the following arguments should match at any sub-component depth.

Examples

Select any ports or terminals named “P1” in component:

>>> component.query("P1")  # doctest: +SKIP

Select any ports or terminals starting with “T” in all references to “SUBCOMPONENT”:

>>> component.query("SUBCOMPONENT", "T.*")  # doctest: +SKIP

Select any ports or terminals named “P0” in any subcomponent whose name starts with “PREFIX”:

>>> component.query("PREFIX.*", "P0")  # doctest: +SKIP

Select any ports or terminals named “GND” in the third (index 2) reference to a component named “ARRAY” at any depth.

>>> component.query(None, "ARRAY", 2, "GND")  # doctest: +SKIP

Select all ports and terminals within subcomponent “SUBCOMPONENT” at any depth

>>> component.query("SUBCOMPONENT", None, ".*")  # doctest: +SKIP

remap_label_layers

remap_label_layers(self, layer_map, include_dependencies=False)

Reassign the layers in this component’s labels.

Args

• layer_map (dict[str | tuple[int, int], str | tuple[int, int]]): Dictionary mapping the existing layers (keys) to the desired ones (values).
• include_dependencies (bool): If set, perform the reassignment in all component dependencies.

Returns

Component: This component.

remap_layers

remap_layers(self, layer_map, include_dependencies=False)

Reassign the layers in this component’s structures.

Args

• layer_map (dict[str | tuple[int, int], str | tuple[int, int]]): Dictionary mapping the existing layers (keys) to the desired ones (values).
• include_dependencies (bool): If set, perform the reassignment in all component dependencies.

Returns

Component: This component.

Example

>>> component.remap_layers({(1, 0): (1, 1), (2, 0): (1, 2)})  # doctest: +SKIP

remove

remove(self, *args, layer=None)

Remove structures, labels, and references from this component.

Args

• args (Polygon | Rectangle | Circle | Path | Label | Reference*): Objects to be removed.
• layer (str | tuple[int] | None): Remove structures from a specific layer.

Returns

Component: This component.

Note

If the structure or label layer is know, specifying it improves the efficiency of this function.

remove_model

remove_model(self, model_name)

Remove a model from this component.

Args

• model_name (str): Name of the model to be removed.

Returns

Model | None: The removed model.

remove_port

remove_port(self, port_name)

Remove a port from this component.

Args

• port_name (str): Name of the port to be removed.

Returns

Port | FiberPort | GaussianPort | None: The removed port.

remove_terminal

remove_terminal(self, terminal_name, remove_structure=True)

Remove a terminal from this component.

Args

• terminal_name (str): Name of the terminal to be removed.
• remove_structure (bool): If True, the terminal structure is also removed from the component.

Returns

Terminal | None: The removed terminal.

remove_virtual_connection

remove_virtual_connection(self, reference, port_name, repetition_index=0)

Remove a virtual connection to a reference in this component.

Args

• reference (Reference): Reference with the connection to be removed.
• port_name (str): Port name with the connection to be removed.
• repetition_index (int): If the reference contains repetitions, select from the list using this index. It must be 0 if it has no repetitions.

Returns

bool: Boolean indicating whether the connection was removed.

remove_virtual_connection_by_instance

remove_virtual_connection_by_instance(self, instance_index, port_name)

Remove a virtual connection to a reference in this component.

Args

• instance_index (int): Index to the instance from the instances list in this component’s Component.get_netlist with the connection to be removed.
• port_name (str): Port name with the connection to be removed.

Returns

bool: Boolean indicating whether the connection was removed.

remove_virtual_net

remove_virtual_net(self, reference, terminal=None, repetition_index=0)

Remove every declared net containing a terminal endpoint.

A single string argument names a component boundary terminal, so remove_virtual_net("GND") and remove_virtual_net(None, "GND") are the same.

Args

• reference (Reference | str | None): Reference with the net to be removed. None denotes a component boundary terminal, and a string names one directly.
• terminal (str | tuple[str, str]): Terminal name with the net to be removed, or a (port_name, terminal_name) tuple for a terminal belonging to a port.
• repetition_index (int): If the reference contains repetitions, select from the list using this index. It must be 0 for a boundary terminal or a reference without repetitions.

Returns

bool: Boolean indicating whether a net was removed.

remove_virtual_net_by_instance

remove_virtual_net_by_instance(self, instance_index, terminal)

Remove every declared net containing an instance terminal.

Args

• instance_index (int): Index to the instance from the instances list in this component’s Component.get_netlist with the net to be removed.
• terminal (str | tuple[str, str]): Terminal name with the net to be removed, or a (port_name, terminal_name) tuple for a terminal belonging to a port.

Returns

bool: Boolean indicating whether a net was removed.

remove_virtual_net_member

remove_virtual_net_member(
    self, reference, terminal=None, repetition_index=0
)

Detach one terminal from the nets holding it.

Component.remove_virtual_net erases every net containing the terminal, removing whole nets; this removes only the terminal, which is how it leaves a global net. A net left with fewer than two terminals is removed. A terminal held by several nets shares one node with all of them, so it leaves every one.

Args

• reference (Reference | str | None): Reference with the terminal to detach. None denotes a component boundary terminal, and a string names one directly.
• terminal (str | tuple[str, str]): Terminal name, or a (port_name, terminal_name) tuple for a terminal belonging to a port.
• repetition_index (int): If the reference contains repetitions, select from the list using this index. It must be 0 for a boundary terminal or a reference without repetitions.

Returns

bool: Boolean indicating whether a terminal was detached.

rename_model

rename_model(self, old_model_name, new_model_name)

Rename the model if model exists in the component.

Args

• old_model_name (str): Name of the model to be renamed.
• new_model_name (str): New name for the model.

Returns

Component: This component.

rename_port

rename_port(self, old_name, new_name)

Rename port in the component.

Args

• old_name (str): Name of the port to be renamed.
• new_name (str): New name for the port.

Returns

Component: This component.

rename_terminal

rename_terminal(self, old_name, new_name)

Rename terminal in the component.

Args

• old_name (str): Name of the terminal to be renamed.
• new_name (str): New name for the terminal.

Returns

Component: This component.

replace_technology

replace_technology(self, new_technology, old_technology=None)

Replace technology for the component and its dependencies.

Args

• new_technology (Technology): New technology for the component.
• old_technology (Technology | None): Technology to be reaplaced.

Returns

Component: This component.

s_matrix

s_matrix(self, frequencies, show_progress=True, model_kwargs={})

Compute the S matrix for this component using its active model.

Args

• frequencies (Sequence[float]): Frequency values at which to calculate the scattering parameters (in Hz).
• show_progress (bool): If True, show computation progress.
• model_kwargs (dict[str, object]): Keyword arguments passed to the active model’s Model.start method. Accepted arguments depend on the model type.

Returns

SMatrix: Computed S matrix.

Example

With a Tidy3DModel as the active model, compute only the responses from mode 0 of P0 to reduce the number and cost of simulations:

>>> s_matrix = component.s_matrix(  # doctest: +SKIP
...     frequencies,
...     model_kwargs={"inputs": ("P0@0",)},
... )

A port name such as ("P0",) selects all modes of that port. All outputs for the selected inputs are returned; responses from unselected inputs are not computed. See Tidy3DModel.start.

select_active_model

select_active_model(self, classification)

Return the electrical or optical active model from this component.

Args

• classification (Literal[“optical”, “electrical”]): Frequency classification.

Returns

Model | None: Active model for the requested classification.

See Also

frequency_classification.

select_ports

select_ports(self, classification)

Return electrical or optical ports from this component.

Args

• classification (Literal[“electrical”, “optical”]): Classification of the returned ports.

Returns

dict[str, Port | FiberPort | GaussianPort]: Dictionary of ports by name.

See Also

frequency_classification.

set_bounds

set_bounds(self, bounds)

Clip the contents of this components to the given rectangular bounds.

Args

• bounds (Sequence[Sequence[float]]): Coordinates of the desired bounding box, specified as ((x_min, y_min), (x_max, y_max)).

Returns

Component: This component.

setup_time_stepper

setup_time_stepper(
    self,
    time_step,
    carrier_frequency=0,
    show_progress=True,
    time_stepper_kwargs={},
)

Initialize a time stepper for this component using its active model.

Args

• time_step (float): The interval between time steps (in seconds).
• carrier_frequency (float): The carrier frequency used to construct the time stepper. The carrier should be omitted from the input signals, as it is handled automatically by the time stepper.
• show_progress (bool): If True, show computation progress.
• time_stepper_kwargs (dict[str, object]): Keyword arguments passed to TimeStepper.setup. Each time stepper type can accept a different set of arguments. Check the documentation for the each time stepper’s setup_state method for more information.

Returns

TimeStepper: Initialized time stepper.

size

size(self, include_ports=True, include_labels=True)

Calculate the component size.

Args

• include_ports (bool): If set, include ports and terminals.
• include_labels (bool): If set, include labels.

Returns

ndarray: The component size.

slice_profile

slice_profile(self, axis, center, length=None, depth=-1)

Get the slice profile of all structures in this component.

This fuction can be used to generate PortSpec.path_profiles from existing geometry, e.g., a complex waveguide cross-section.

Args

• axis (Literal[“x”, “y”]): Cross-sectional axis.
• center (Sequence[float] | complex): Center of the slice segment.
• length (float | None): Length of the slice segment. If None, an infinite line is used.
• depth (int): If not negative, limits the depth of references to gather structures from.

Returns

list[tuple[float, float, tuple[int, int]]]: List of tuples of (width, offset, layer).

Example

>>> component = pf.parametric.straight(port_spec="Strip", length=1)
>>> component.slice_profile("x", (0.5, 0))
[(2.5, 0.0, (1, 0)), (0.5, 0.0, (2, 0))]

structure_count

structure_count(self)

Return the number structures in this component, excluding dependencies.

Returns

int: Number of structures in the component.

tree_view

tree_view(self, by_reference=False, interactive=False)

Create a tree view of this component and its dependencies.

Create a temporary object fit for representation in a REPL or notebook environment.

Args

• by_reference (bool): If True shows all references (with index) within the component. Otherwise, only shows unique dependencies.
• interactive (bool): If True, the notebook visualization will use interactive folds and includes SVG previews.

Returns

object: Tree view object.

Example

>>> component.tree_view()  # doctest: +SKIP
MAIN
├─ SUBCOMPONENT1
└─ SUBCOMPONENT2

update

update(self, *args, **kwargs)

Update this component if it was created as a parametric component.

All contents of the component are updated with the contents from the updated version. object contents (structures, models, ports, etc.) or modifications introduced after the component creation (outside of the original parametric function) are not propagated.

The only exception to this rule is the component’s active models. The name of the active models are stored before the update and, if a model with the same name exists in the updated component, it will be made active.

Args

• *args (object): Positional arguments to the parametric component function.
• **kwargs (object): Keyword arguments to the parametric component function.

Returns

Component: This component.

Note

The original keyword arguments used to generate the component are stored and updated with the passed kwargs. This updated version is used in the function call and will be stored for future updates. Positional arguments are not stored.

See Also

• Parametric Component Library
• Custom Parametric Components

write_gds

write_gds(
    self,
    filename='',
    paths_to_polygons=True,
    fracture_limit=0,
    pre_export_function=None,
)

Export this component as a GDSII file.

Args

• filename (str): Output file name. If empty, it will be derived from the component name.
• paths_to_polygons (bool): If True, all Path structures will be stored as polygonal contours.
• fracture_limit (int): Polygons with a number of vertices above this limit will be fractured into multiple polygons. The limit is ignored if not above 4.
• pre_export_function (Callable | None): Function called for each component before exporting the layout (see note in write_layout for more information).

Returns

Component: This component.

write_oas

write_oas(
    self,
    filename='',
    paths_to_polygons=True,
    compression_level=9,
    library_properties=None,
    pre_export_function=None,
)

Export this component as an OASIS file.

Args

• filename (str): Output file name. If empty, it will be derived from the component name.
• paths_to_polygons (bool): If True, all Path structures will be stored as polygonal contours.
• compression_level (int): Level of compression of the file. Disabled if set to 0. Maximal compression level is 9.
• library_properties (Properties | None): Properties to be included in the exported library.
• pre_export_function (Callable | None): Function called for each component before exporting the layout (see note in write_layout for more information).

Returns

Component: This component.

Attributes

Attribute	Description
active_model	dict[str, Model] | Model | None: Current active model for this component (read only).
active_model_name	dict[str, str] | str | None: Current active model name for this component (read only).
labels	dict[tuple[int, int], Label]: Component labels indexed by layer (read only).
models	dict[str, Model]: Component models (read only).
name	str: Component name.
parametric_function	str | None: Function used to update a parametric component.
parametric_kwargs	dict[str, object]: Keyword arguments used to update a parametric component.
ports	dict[str, Port | FiberPort | GaussianPort]: Component ports (read only).
properties	Properties: Object properties.
random_variables	list[RandomVariable]: Random variables associated to this component’s parameters.
references	list[Reference]: Component references (read only).
structures	dict[tuple[int, int], Rectangle | Circle | Polygon | Path]: Component structures indexed by layer (read only).
technology	Technology: Component technology.
terminals	dict[str, Terminal]: Component terminals (read only).
virtual_connections	list[tuple[tuple[Reference | None, str, int], tuple[Reference | None, str, int]]]: Virtual connections between this component’s references. Each endpoint is a reference, its port name, and the reference’s repetition index (read only).
virtual_connections_by_instance	list[tuple[tuple[int, str], tuple[int, str]]]: Virtual connections between this component’s references (as indices into the instances list from Component.get_netlist; read only).
virtual_nets	list[list[tuple[Reference | None, str | tuple[str, str], int]]]: Declared N-way nets. Each member is a reference, a terminal, and the reference’s repetition index; a None reference denotes the component’s own boundary terminal (always with repetition index 0) and a (port name, terminal name) tuple a terminal owned by a port (read only).

active_model

dict[str, Model] | Model | None: Current active model for this component (read only).

active_model_name

dict[str, str] | str | None: Current active model name for this component (read only).

labels

dict[tuple[int, int], Label]: Component labels indexed by layer (read only).

models

dict[str, Model]: Component models (read only).

name

str: Component name.

parametric_function

str | None: Function used to update a parametric component.

parametric_kwargs

dict[str, object]: Keyword arguments used to update a parametric component.

ports

dict[str, Port | FiberPort | GaussianPort]: Component ports (read only).

properties

Properties: Object properties.

random_variables

list[RandomVariable]: Random variables associated to this component’s parameters.

references

list[Reference]: Component references (read only).

structures

dict[tuple[int, int], Rectangle | Circle | Polygon | Path]: Component structures indexed by layer (read only).

technology

Technology: Component technology.

terminals

dict[str, Terminal]: Component terminals (read only).

virtual_connections

list[tuple[tuple[Reference | None, str, int], tuple[Reference | None, str, int]]]: Virtual connections between this component’s references. Each endpoint is a reference, its port name, and the reference’s repetition index (read only).

virtual_connections_by_instance

list[tuple[tuple[int, str], tuple[int, str]]]: Virtual connections between this component’s references (as indices into the instances list from Component.get_netlist; read only).

virtual_nets

list[list[tuple[Reference | None, str | tuple[str, str], int]]]: Declared N-way nets. Each member is a reference, a terminal, and the reference’s repetition index; a None reference denotes the component’s own boundary terminal (always with repetition index 0) and a (port name, terminal name) tuple a terminal owned by a port (read only).