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)	Set selected model as active (i.e., default for computing the S matrix).
`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_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.
`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.
`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_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.
`set_bounds`(bounds)	Clip the contents of this components to the given rectangular bounds.
`structure_count`()	Return the number structures in this component, excluding 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.
`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)¶

Set selected model as active (i.e., default for computing the S matrix).

Parameters:: model_name – Name of the model to set as active.
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 – Set the inserted model as active.

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_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 (3D ports are never included).
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)¶

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.

Returns:

List of detected ports.

Note

The returned ports are not automatically added to the component.

See also

Ports guide

extrude(port_extension=0, heal=False, extrusion_tolerance=0)¶

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.

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

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

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.

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.

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 model. The name of the active model is 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.