Reference¶

class photonforge.Reference(component, origin=(0, 0), rotation=0, scaling=1, x_reflection=False, columns=1, rows=1, spacing=(0, 0), technology_updates={}, component_updates={}, model_updates={}, s_matrix_kwargs={})¶

Reference to a 2D component.

Parameters:

component (Component) – Target component to be used as a sub-component.
origin (Sequence[float] | complex) – Translation vector for this reference.
rotation (float) – Rotation (in degrees) of this reference.
scaling (float) – Reference scaling factor.
x_reflection (bool) – Flag controlling mirroring across the x axis.
columns (int) – Number of repetitions along the x axis.
rows (int) – Number of repetitions along the y axis.
spacing (Sequence[float] | complex) – Displacement vector between repetitions.
technology_updates (dict[str, Any]) – Keyword arguments for Technology.update() when calling Reference.update().
component_updates (dict[str, Any]) – Keyword arguments for Component.update() when calling Reference.update().
model_updates (dict[str, Any]) – Keyword arguments used for Model.update() when calling Reference.update().
s_matrix_kwargs (dict[str, Any]) – Keyword arguments used when calling Component.s_matrix() from a CircuitModel.

Examples

>>> device = Component("DEVICE")
>>> device.add(Rectangle(center=(0, 0), size=(0.5, 0.2)))
>>> ref1 = Reference(device)
>>> ref2 = Reference(device, (2, 2), rotation=90)
>>> ref3 = Reference(
...     device, (4, 0), columns=2, rows=3, spacing=(2, 1)
... )
>>> main = Component("Main")
>>> main.add(ref1, ref2, ref3)

Note

Transformations are not supported by reference arrays. Alternatively the following methods can be used:

>>> transformed_device = pf.Component("TRANSFORMED")
>>> transformed_device.add(Reference(device, rotation=45))
>>> array = Reference(
...     transformed_device, columns=2, rows=3, spacing=(2, 1)
... )
>>> main1 = Component("Array of rotated devices")
>>> main1.add(array)

>>> device_array = pf.Component("REPEATED")
>>> device_array.add(
...     Reference(device, columns=2, rows=3, spacing=(2, 1))
... )
>>> transformed_array = Reference(device_array, rotation=45)
>>> main2 = Component("Rotated array of devices")
>>> main2.add(transformed_array)

Methods

`add_gds_property`(value)	Add a custom property to this object compatible with GDSII files.
`bounds`()	Calculate the reference bounds.
`connect`(port_name, to_port[, repetition_index])	Move and rotate this reference to connect it to a port.
`convex_hull`()	Calculate the convex hull of this reference.
`copy`([deep, copy_technology])	Create a copy of this reference.
`get_labels`([layer, depth])	Get all labels in the sub-component and its references.
`get_ports`([port_name])	Return the ports created by this reference inherited from its component.
`get_repetition`([repetition_index])	Create new references by applying the repetition in this reference.
`get_structures`([layer, depth])	Get all structures in the sub-component and its references.
`get_terminals`([terminal_name])	Return the terminals created by this reference inherited from its component.
`mirror`([axis_endpoint, axis_origin])	Mirror this reference.
`query`(*args)	Query ports and terminals from the reference or its dependencies.
`rotate`(rotation[, center])	Rotate this reference around a specific center.
`scale`(scaling[, center])	Scale this reference.
`size`()	Calculate the reference size.
`transform`([translation, rotation, scaling, ...])	Apply a transformation to this reference: `self = translate(rotate(mirror(scale(self))))`
`transformed_component`(name[, repetition_index])	Create a new component by applying this reference's transformation.
`translate`(translation)	Translate this reference.
`update`([technology_updates, ...])	Apply updates to this reference's technology, component and model.

Attributes

`columns`	Number of reference columns.
`component`	Referenced component.
`component_name`	Name of the referenced component (read only).
`component_updates`	Keyword arguments used for calling `Component.update()` before calculating the S matrix from a `CircuitModel`.
`model_updates`	Keyword arguments used for calling `Model.update()` before calculating the S matrix from a `CircuitModel`.
`origin`	Reference origin.
`properties`	Object properties.
`rotation`	Reference rotation.
`rows`	Number of reference rows.
`s_matrix_kwargs`	Keyword arguments used when calling `Component.s_matrix()` from a `CircuitModel`.
`scaling`	Reference scaling.
`spacing`	Spacing between reference columns and rows.
`technology_updates`	Keyword arguments used for calling `Technology.update()` before calculating the S matrix from a `CircuitModel`.
`x_max`	Upper bound in the x axis.
`x_mid`	Bounding box center in the x axis.
`x_min`	Lower bound in the x axis.
`x_reflection`	Reference x_reflection.
`y_max`	Upper bound in the y axis.
`y_mid`	Bounding box center in the y axis.
`y_min`	Lower bound in the y axis.

add_gds_property(value)¶

Add a custom property to this object compatible with GDSII files.

Parameters:

attribute (int) – Property number.
value (str) – Property value.

bounds()¶

Calculate the reference bounds.

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

columns¶

Number of reference columns.

Type:: int

component¶

Referenced component.

Type:: Component

component_name¶

Name of the referenced component (read only).

Type:: str

component_updates¶

Keyword arguments used for calling Component.update() before calculating the S matrix from a CircuitModel.

Type:: dict[str, Any]

connect(port_name, to_port, repetition_index=0)¶

Move and rotate this reference to connect it to a port.

Parameters:

port_name (str) – Name of the port from the referenced component that will be connected to to_port.
to_port (Port) – Port instance to connect to.
repetition_index (int) – If this reference contains repetitions, select from the list using this index. It must be 0 if this reference has no repetitions.

Returns:

This reference.

Return type:

Reference

convex_hull()¶

Calculate the convex hull of this reference.

Returns:: Vertices of the convex hull.
Return type:: ndarray

copy(deep=False, copy_technology=False)¶

Create a copy of this reference.

Parameters:

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:

New copy.

Return type:

Reference

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

Get all labels in the sub-component and its references.

Parameters:

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.

Returns:

List of labels.

Return type:

list[Label]

get_ports(port_name=None)¶

Return the ports created by this reference inherited from its component.

Parameters:: port_name (str | None) – If set, uses only the named port from the component and returs a single list, otherwise all component ports are transformed and returned in a dictionary.
Returns:: Ports created through this reference’s transform.
Return type:: list[Port | FiberPort | GaussianPort] | dict[str, list[Port | FiberPort | GaussianPort]

Note

Indexing into a reference can also be used to get ports in a similar manner: reference[port_name] has the same effect as reference.get_ports(port_name), except that it doesn’t create a list if only a single port is returned.

get_repetition(repetition_index=-1)¶

Create new references by applying the repetition in this reference.

Parameters:: repetition_index (int) – If non-negative, only the repetition with the given index is created. Otherwise, all repetitions are returned in a list.
Returns:: New reference or reference list.
Return type:: Reference | list[Reference]

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

Get all structures in the sub-component and its references.

Parameters:

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.

Returns:

List of structures.

Return type:

list[Rectangle | Circle | Polygon | Path]

get_terminals(terminal_name=None)¶

Return the terminals created by this reference inherited from its component.

Parameters:: terminal_name (str | None) – If set, uses only the named terminal from the component and returs a single list, otherwise all component terminals are transformed and returned in a dictionary.
Returns:: Terminals created through this reference’s transform.
Return type:: list[Terminal] | dict[str, list[Terminal]]

Note

Indexing into a reference can also be used to get terminals in a similar manner: reference[terminal_name] has the same effect as reference.get_terminals(terminal_name), except that it doesn’t create a list if only a single terminal is returned.

mirror(axis_endpoint=(1, 0), axis_origin=(0, 0))¶

Mirror this reference.

Parameters:

axis_endpoint (Sequence[float] | complex) – Mirror axis endpoint.
axis_origin (Sequence[float] | complex) – Mirror axis origin.

Returns:

This reference.

Return type:

Reference

model_updates¶

Keyword arguments used for calling Model.update() before calculating the S matrix from a CircuitModel.

Type:: dict[str, Any]

origin¶

Reference origin.

Type:: ndarray

properties¶

Object properties.

Type:: Properties

query(*args)¶

Query ports and terminals from the reference or its dependencies.

Parameters:: *args (str | int | None) – Strings, integers or None representing a reference specification ending with a port/terminal specification (see below for further information).
Returns:: Selected ports and terminals. If the resulting selection contains only a single element, the element itself is returned.
Return type:: Port | FiberPort | GaussianPort | Terminal | list[Port | FiberPort | GaussianPort | Terminal]

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.