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.
`mirror`([axis_endpoint, axis_origin])	Mirror this reference.
`rotate`(rotation[, center])	Rotate this reference around a specific center.
`scale`(scaling[, center])	Scale this reference.
`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 (read only).
`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 (read only).

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.

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.

rotate(rotation, center=(0, 0))¶

Rotate this reference around a specific center.

Parameters:

rotation – Rotation angle in degrees.
center – Center of rotation.

Returns:

This reference.

rotation¶: Reference rotation.

rows¶: Number of reference rows.

s_matrix_kwargs¶: Keyword arguments used when calling Component.s_matrix() from a CircuitModel.

scale(scaling, center=(0, 0))¶

Scale this reference.

Parameters:

scaling – Scaling factor.
center – Center of scaling.

Returns:

This reference.

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.

transform(translation=(0, 0), rotation=0, scaling=1, x_reflection=False)¶

Apply a transformation to this reference: self = translate(rotate(mirror(scale(self))))

Parameters:

translation – Translation vector.
rotation – Rotation angle in degrees.
scaling – Magnification factor.
x_reflection – Mirror across the horizontal axis.

Returns:

This reference.

transformed_component(name, repetition_index=0)¶

Create a new component by applying this reference’s transformation.

Parameters:

name – New component name.
repetition_index – For reference arrays, which element in the repetition to use.

Returns:

New Component

translate(translation)¶

Translate this reference.

Parameters:: translation – Translation vector.
Returns:: This reference.

update(technology_updates={}, component_updates={}, model_updates={}, chain_technology_updates=True)¶

Apply updates to this reference’s technology, component and model.

Update parameters are taken from Reference.technology_updates, Reference.component_updates and Reference.model_updates, but can be overridden by the function arguments with matching keys.

The technology is updated first, then all components that use the updated technology (if ‘chain_technology_updates’ is True), the referenced component itself, and, at last, its active model.

Parameters:

technology_updates – Updates to the technology of the referenced component. The values in this dictionary take precedence over Reference.technology_updates.
component_updates – Updates to the referenced component. The values in this dictionary take precedence over Reference.component_updates.
model_updates – Updates to the active model of the referenced component. The values in this dictionary take precedence over Reference.model_updates.
chain_technology_updates – if set, a technology update will trigger an update for all components using that technology.

Returns:

List of tuples with the updated objects and their original parametric keyword arguments, in the order they were updated.