Reference¶

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

Reference to a 2D component.

Parameters:

component – Target component to be used as a sub-component.
origin – Translation vector for this reference.
rotation – Rotation (in degrees) of this reference.
scaling – Reference scaling factor.
x_reflection – Flag controlling mirroring across the x axis.
columns – Number of repetitions along the x axis.
rows – Number of repetitions along the y axis.
spacing – Displacement vector between repetitions.
technology_updates – Keyword arguments for Technology.update() when calling Reference.update().
component_updates – Keyword arguments for Component.update() when calling Reference.update().
model_updates – Keyword arguments used for Model.update() when calling Reference.update().
s_matrix_kwargs – 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

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

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

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.

connect(port_name, to_port, repetition_index=0)¶

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

Parameters:

port_name – Name of the port from the referenced component that will be connected to to_port.
to_port – Port instance to connect to.
repetition_index – 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.

convex_hull()¶

Calculate the convex hull of this reference.

Returns:: Vertices of the convex hull.

copy(deep=False, copy_technology=False)¶

Create a copy of this reference.

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.

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

Get all labels in the sub-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.

Returns:

List of labels.

get_ports(port_name=None)¶

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

Parameters:: port_name – If set, uses only the named port from the component.
Returns:: List of ports created through this reference’s transform.

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

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

Get all structures in the sub-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.

Returns:

List of structures.

get_terminals(terminal_name=None)¶

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

Parameters:: terminal_name – If set, uses only the named terminal from the component.
Returns:: List of terminals created through this reference’s transform.

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 – Mirror axis endpoint.
axis_origin – Mirror axis origin.

Returns:

This reference.

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

origin¶: Reference origin.

query(*args)¶

Query ports and terminals from the reference or its dependencies.

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.