Component¶

class photonforge.Component(name='', technology=None)¶

Polygonal geometric object.

Parameters:

name – Name of the component.
technology – Technology specification for this component.

Methods

`activate_model`(model_name[, classification])	Set model as active for S matrix computation.
`add`(*args)	Add structures, labels, and references to this component.
`add_model`(model[, model_name, set_active])	Add a model to this component.
`add_port`(port[, port_name])	Add a port to this component.
`add_reference`(reference)	Add a reference to this component.
`add_reference_ports`([include_dependencies, ...])	Add a reference to this component.
`add_terminal`(terminal[, terminal_name, ...])	Add a terminal to this component.
`add_virtual_connection`(reference0, ...[, ...])	Adds a virtual connection between references in this component.
`add_virtual_connection_by_instance`(...)	Adds a virtual connection between references in this component.
`bounds`([include_ports])	Calculate the component bounds.
`build_mask`(mask_spec[, heal])	Compute the component's mask based on a mask specification.
`convex_hull`()	Calculate the convex hull of this component.
`copy`([deep, copy_technology])	Create a copy of this component.
`dependencies`()	Return a list of components recursively present in this component's references.
`detect_dependency_cycle`()	Check wheter this component includes a dependency cycle.
`detect_ports`([specs, bounds, ...])	Try to detect ports in this components base on its structures.
`disconnected_reference_ports`()	Get all ports from references that are not connected.
`extrude`([port_extension, heal, ...])	Extrude this component according to its technology specification.
`filter_label_layers`(layers, keep[, ...])	Remove labels from the component based on their layer.
`filter_layers`(layers, keep[, ...])	Remove structures from the component based on their layer.
`flatten`()	Replace component references with their corresponding contents.
`from_bytes`(bytes)	Create a component object from its byte representation.
`get_instance_maps`()	Compute mappings between references and instace indices.
`get_labels`([layer, depth, skip_components])	Get all labels in the component and its references.
`get_netlist`()	Return a netlist representation of this component.
`get_structures`([layer, depth, skip_components])	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`([include_dependencies, ...])	Return the layers used in this component.
`query`(*args)	Query ports and terminals from the component or its references.
`remap_label_layers`(layer_map[, ...])	Reassign the layers in this component's labels.
`remap_layers`(layer_map[, include_dependencies])	Reassign the layers in this component's structures.
`remove`(*args[, layer])	Remove structures, labels, and references from this component.
`remove_model`(model_name)	Remove a model from this component.
`remove_port`(port_name)	Remove a port from this component.
`remove_terminal`(terminal_name[, ...])	Remove a terminal from this component.
`remove_virtual_connection`(reference, port_name)	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.
`s_matrix`(frequencies[, show_progress, ...])	Compute the S matrix for this component using its active model.
`select_active_model`(classification)	Return the electrical or optical active model from this component.
`select_ports`(classification)	Return electrical or optical ports from this component.
`set_bounds`(bounds)	Clip the contents of this components to the given rectangular bounds.
`size`([include_ports])	Calculate the component size.
`structure_count`()	Return the number structures in this component, excluding dependencies.
`tree_view`([by_reference, interactive])	Create a tree view of this component and its dependencies.
`update`(args, *kwargs)	Update this component if it was created as a parametric component.
`write_gds`([filename, paths_to_polygons, ...])	Export this component as a GDSII file.
`write_oas`([filename, paths_to_polygons, ...])	Export this component as an OASIS file.

Attributes

`active_model`	Current active model for this component (read only).
`as_bytes`	Byte representation of the component (read only).
`labels`	Dictionary of component labels by layer (read only).
`models`	Dictionary of component models (read only).
`name`	Component name.
`parametric_function`	Function used to update a parametric component.
`parametric_kwargs`	Keyword arguments used to update a parametric component.
`ports`	Dictionary of component ports (read only).
`random_variables`	List of `monte_carlo.RandomVariable` associated to this component's parameters.
`references`	List of component references (read only).
`structures`	Dictionary of component structures by layer (read only).
`technology`	Component technology.
`terminals`	Dictionary of component terminals (read only).
`virtual_connections`	List of virtual connections between this component's references (read only).
`virtual_connections_by_instance`	List of virtual connections between this component's references (as indices into the instances list from `Component.get_netlist()`; read only).

activate_model(model_name, classification=None)¶

Set model as active for S matrix computation.

Parameters:

model_name – Name of the model to set as active.
classification – One of "optical" or "electrical" to activate for a specific frequency range. If None, activates the model for both frequency ranges.

Returns:

Activated model.

active_model¶: Current active model for this component (read only).

add(*args)¶

Add structures, labels, and references to this component.

Parameters:: *args – Structures, labels, references or sub-components to be added, along with the desired layers for the structures. Must be instances o Rectangle, Circle, :class:`Polygon, Path, Label, Reference, Component, or a layer name or tuple.
Returns:: This component.

Example

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

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

Add a model to this component.

Parameters:

model – Model to be added. A sequence of models can be passed to add all simultaneously.
model_name – 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 the list size - 1.
set_active – Flag used to set the model as active. If "optical" or "electrical", set only for the respective ferquency range.

Returns:

The model name(s).

add_port(port, port_name=None)¶

Add a port to this component.

Parameters:

port – Port to be added. A sequence or dictionary of ports can be passed to add all simulataneously.
port_name – 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:

The port name(s).

add_reference(reference)¶

Add a reference to this component.

Parameters:: reference – Instance of Reference or Component to be added.
Returns:: Reference added.

add_reference_ports(include_dependencies=False, add_model=None)¶

Add a reference to this component.

Parameters:

include_dependencies – If set, add reference ports to dependencies before operating in this component.
add_model – If a Model instance is given, it 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 of names of the ports added to this component.

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

Add a terminal to this component.

Parameters:

terminal – Terminal to be added. A sequence or dictionary of terminals can be passed to add all simulataneously.
terminal_name – 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 – If True, the terminal structure is also added to the component.
structure_layer – Layer to add the terminal structure. If None, the Terminal.routing_layer is used.

Returns:

The terminal name(s).

add_virtual_connection(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.

Parameters:

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

Returns:

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

Parameters:

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

Returns:

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.

as_bytes¶: Byte representation of the component (read only).

bounds(include_ports=True)¶

Calculate the component bounds.

Parameters:: include_ports – If set, include dimensions of planar ports in the computation.
Returns:: The lower-left and upper-right corners of the bounding box of the component: ((min_x, min_y), (max_x, max_y)).

build_mask(mask_spec, heal=False)¶

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

Parameters:

mask_spec – Mask specification.
heal – 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 of polygons that make up the mask.

convex_hull()¶

Calculate the convex hull of this component.

Returns:: Vertices of the convex hull.

copy(deep=False, copy_technology=False)¶

Create a copy of this component.

Parameters:

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

Returns:

New copy.

dependencies()¶

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

Returns:: List of components.

detect_dependency_cycle()¶

Check wheter this component includes a dependency cycle.

Returns:: First component found that creates a cycle.

Note

This method returns the first component that creates a cycle, but others might exist.

detect_ports(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.

Parameters:

specs – Iterable of PortSpec or their names to be uses as base for searching. If set to None, all specifications from the component technology are used.
bounds – Limit the search for ports within these bounds, specified as ((x_min, y_min), (x_max, y_max)).
skip_internal_connections – 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 – Limit the search to ports at the devices boundaries. One of "xy", "x", "+x", "-x", "y", "+y", or "-y".
boundary_margin – When searching on boundaries, include the region within this margin from the component bounds.
minimal_turn_angle – Minimal turning angle (in degrees) between adjacent polygon edges to consider the edges as candidates for port.

Returns:

List of detected ports.

Note

The returned ports are not automatically added to the component.

See also

Ports guide

disconnected_reference_ports()¶

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 disconnected ports.

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

Extrude this component according to its technology specification.

Parameters:

port_extension – Extension length for ports marked as extended.
heal – 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 – Minimal dimension to search for topological changes in angled extrusions or fallback to an orthogonal profile. A value of 0 or less defaults to config.tolerance.
classsification – Frequency classification indicating which type of medium to use. One of "electrical" or "optical".
used_extrusions – If this argument is set to a list, all extrusion specifications that are effectively used will be appended to it.

Returns:

List of polyhedra.

filter_label_layers(layers, keep, include_dependencies=False)¶

Remove labels from the component based on their layer.

Parameters:

layers – Iterable of layers to keep or to remove.
keep – Boolean flag indicating whether the layers represent the layers that should be removed (False) or kept (True).
include_dependencies – If set, filter all component dependencies too.

Returns:

This component.

filter_layers(layers, keep, include_dependencies=False)¶

Remove structures from the component based on their layer.

Parameters:

layers – Iterable of layers to keep or to remove.
keep – Boolean flag indicating whether the layers represent the layers that should be removed (False) or kept (True).
include_dependencies – If set, filter all component dependencies too.

Returns:

This component.

Example

>>> component.filter_layers([(1, 0), (3, 0)], True)

flatten()¶

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:: This component.

static from_bytes(bytes)¶

Create a component object from its byte representation.

Parameters:: bytes – Byte sequence with the component data.
Returns:: Component instance.

get_instance_maps()¶

Compute mappings between references and instace indices.

Returns:: Dictionary mapping from (reference_index, repetition_index) to instance_index and a list mapping from instance_index to (reference_index, repetition_index).

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

Get all labels in the component and its references.

Parameters:

layer – If specified, only labels in this layer are returned.
depth – If not negative, limits the depth of search into references.
skip_components – Iterable of Component or component names whose polygons should not be returned.

Returns:

List of labels.

Note

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

get_netlist()¶

Return a netlist representation of this component.

The netlist is a dictionary containing 4 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.
‘connections’: list of tuples with 2 instance ports that are connected within the netlist. The number of modes in connected ports is guaranteed to be the same.
‘virtual connections’: list of tuples with 2 instance ports that are virtually connected within the netlist. The number of modes in connected ports is guaranteed to be the same.

Returns:: Dictionary with keys ‘instances’, ‘ports’, ‘connections’, and ‘virtual connections’.

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

Get all structures in the component and its references.

Parameters:

layer – If specified, only structures in this layer are returned.
depth – If not negative, limits the depth of search into references.
skip_components – Iterable of Component or component names whose polygons should not be returned.

Returns:

List of structures.

Note

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

invalid_virtual_connections()¶

Return invalid virtual connections in this component.

Returns:: List of invalid connections.

label_count()¶

Return the number labels in this component, excluding dependencies.

Returns:: Number of labels in the component.

labels¶: Dictionary of component labels by layer (read only).

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

Return the layers used in this component.

Parameters:

include_dependencies – If set, the return list also includes layers used in dependencies.
include_structures – Whether to include structure layers or not.
include_labels – Whether to include label layers or not.

Returns:

Layer set.

models¶: Dictionary of component models (read only).

name¶: Component name.

parametric_function¶: Function used to update a parametric component.

parametric_kwargs¶: Keyword arguments used to update a parametric component.

ports¶: Dictionary of component ports (read only).

query(*args)¶

Query ports and terminals from the component or its references.

Parameters:: *args – Sequence of strings, integers or None representing a reference specification ending with a port/terminal specification (see below for further information).
Returns:: List of 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")

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

>>> component.query("SUBCOMPONENT", "T.*")

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

>>> component.query("PREFIX.*", "P0")

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

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

>>> component.query("SUBCOMPONENT", None, ".*")

random_variables¶: List of monte_carlo.RandomVariable associated to this component’s parameters.

references¶: List of component references (read only).

remap_label_layers(layer_map, include_dependencies=False)¶

Reassign the layers in this component’s labels.

Parameters:

layer_map – Dictionary mapping the existing layers (keys) to the desired ones (values).
include_dependencies – If set, perform the reassignment in all component dependencies.

Returns:

This component.

remap_layers(layer_map, include_dependencies=False)¶

Reassign the layers in this component’s structures.

Parameters:

layer_map – Dictionary mapping the existing layers (keys) to the desired ones (values).
include_dependencies – If set, perform the reassignment in all component dependencies.

Returns:

This component.

Example

>>> component.remap_layers({(1, 0): (1, 1), (2, 0): (1, 2)})

remove(*args, layer=None)¶

Remove structures, labels, and references from this component.

Parameters:

*args – Structures, labels, or references to be removed.
layer – Remove structures from a specific layer.

Returns:

This component.

Note

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

remove_model(model_name)¶

Remove a model from this component.

Parameters:: model_name – Name of the model to be removed.
Returns:: The removed model, or None if it does not exist.

remove_port(port_name)¶

Remove a port from this component.

Parameters:: port_name – Name of the port to be removed.
Returns:: The removed port, or None if it does not exist.

remove_terminal(terminal_name, remove_structure=True)¶

Remove a terminal from this component.

Parameters:

terminal_name – Name of the terminal to be removed.
remove_structure – If True, the terminal structure is also removed from the component.

Returns:

The removed terminal, or None if it does not exist.

remove_virtual_connection(reference, port_name, repetition_index=0)¶

Remove a virtual connection to a reference in this component.

Parameters:

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

Returns:

Boolean indicating whether the connection was removed.

remove_virtual_connection_by_instance(instance_index, port_name)¶

Remove a virtual connection to a reference in this component.

Parameters:

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

Returns:

Boolean indicating whether the connection was removed.

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

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

Parameters:

frequencies – Sequence of frequency values at which to calculate the scattering parameters (in Hz).
show_progress – If True, show overall computation progress.
model_kwargs – Keyword arguments passed to the model call. Each model type can accept a different set of arguments. Check the documentation for the specific model for more information.

Returns:

Computed SMatrix.

select_active_model(classification)¶

Return the electrical or optical active model from this component.

Parameters:: classification – One of "electrical" or "optical".
Returns:: Active model for the requested classification.

See also

frequency_classification().

select_ports(classification)¶

Return electrical or optical ports from this component.

Parameters:: classification – One of "electrical" or "optical".
Returns:: Dictionary of ports indexed by name.

See also

frequency_classification().

set_bounds(bounds)¶

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

Parameters:: bounds – Coordinates of the desired bounding box, specified as ((x_min, y_min), (x_max, y_max)).
Returns:: This component.

size(include_ports=True)¶

Calculate the component size.

Parameters:: include_ports – If set, include dimensions of planar ports in the computation.
Returns:: The component size.

structure_count()¶

Return the number structures in this component, excluding dependencies.

Returns:: Number of structures in the component.

structures¶: Dictionary of component structures by layer (read only).

technology¶: Component technology.

terminals¶: Dictionary of component terminals (read only).

tree_view(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.

Parameters:

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

Returns:

Tree view object.

Example

>>> component.tree_view()
MAIN
├─ SUBCOMPONENT1
└─ SUBCOMPONENT2

update(*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. Any 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.

Parameters:

*args – Positional arguments to the parametric component function.
**kwargs – Keyword arguments to the parametric component function.

Returns:

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

virtual_connections¶: List of virtual connections between this component’s references (read only).

virtual_connections_by_instance¶: List of virtual connections between this component’s references (as indices into the instances list from Component.get_netlist(); read only).

write_gds(filename='', paths_to_polygons=True, fracture_limit=0)¶

Export this component as a GDSII file.

Parameters:

filename – Output file name. If empty, it will be derived from the component name.
paths_to_polygons – If True, all Path structures will be stored as polygonal contours.
fracture_limit – Polygons with a number of vertices above this limit will be fractured into multiple polygons. The limit is ignored if not above 4.

Returns:

This component.

write_oas(filename='', paths_to_polygons=True, compression_level=9)¶

Export this component as an OASIS file.

Parameters:

filename – Output file name. If empty, it will be derived from the component name.
paths_to_polygons – If True, all Path structures will be stored as polygonal contours.
compression_level – Level of compression of the file. Disabled if set to 0. Maximal compression level is 9.

Returns:

This component.