Reference

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={},
    time_stepper_kwargs={},
)

Reference to a 2D component.

Args

• 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 (at least 1).
• rows (int): Number of repetitions along the y axis (at least 1).
• spacing (Sequence[float] | complex): Displacement vector between repetitions.
• technology_updates (dict[str, object]): Keyword arguments for Technology.update when calling Reference.update.
• component_updates (dict[str, object]): Keyword arguments for Component.update when calling Reference.update.
• model_updates (dict[str, object]): Keyword arguments used for Model.update when calling Reference.update.
• s_matrix_kwargs (dict[str, object]): Keyword arguments used when calling Component.s_matrix from a CircuitModel.
• time_stepper_kwargs (dict[str, object]): Keyword arguments used when setting up a time stepper from a CircuitModel (e.g. a per-reference carrier frequency and fit grid).

Examples

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

Note

Array spacing is expressed in parent coordinates. Rotation, scaling, and reflection apply to the repeated component geometry, not the spacing vectors.

Note

Because components have multiple models, model_updates can be specified per model as a dictionary of keyword arguments using the model names as keys. Only the currently active component model will be updated.

In this example, only the "Waveguide" model (default model for the bend) is updated:

>>> component = pf.parametric.bend(port_spec="Strip", radius=10)
>>> model_updates = {
...     "Waveguide": {"length": 1.0},  # Updates for Waveguide model
...     "Tidy3D": {"verbose": False},  # Updates for Tidy3D model
... }
>>> reference = pf.Reference(component, model_updates=model_updates)
>>> reference.update()
[(WaveguideModel(n_complex=None, length=1.0, ...), {...})]

Methods

Method	Description
add_gds_property	Add a custom property to this object compatible with GDSII files.
bounds	Calculate the reference bounds.
center	Calculate the reference center.
connect	Move and rotate this reference to connect it to a port.
convex_hull	Calculate the convex hull of this reference.
copy	Create a copy of this reference.
get_labels	Get all labels in the sub-component and its references.
get_ports	Return the ports created by this reference inherited from its component.
get_repetition	Create new references by applying the repetition in this reference.
get_structures	Get all structures in the sub-component and its references.
get_terminals	Return the terminals created by this reference inherited from its
mirror	Mirror this reference.
query	Query ports and terminals from the reference or its dependencies.
rotate	Rotate this reference around a specific center.
scale	Scale this reference.
size	Calculate the reference size.
transform	Apply a transformation to this reference:
transformed_component	Create a new component by applying this reference’s transformation.
translate	Translate this reference.
update	Apply updates to this reference’s technology, component and model.

add_gds_property

add_gds_property(attribute, value)

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

Args

• attribute (int): Property number.
• value (str): Property value.

bounds

bounds(self, include_labels=True)

Calculate the reference bounds.

Args

• include_labels (bool): If set, include labels.

Returns

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

center

center(self, include_labels=True)

Calculate the reference center.

Args

• include_labels (bool): If set, include labels.

Returns

ndarray: The reference center.

connect

connect(self, port_name, to_port, repetition_index=0)

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

Args

• 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

Reference: This reference.

convex_hull

convex_hull(self, include_labels=True)

Calculate the convex hull of this reference.

Args

• include_labels (bool): If set, include labels.

Returns

ndarray: Vertices of the convex hull.

copy

copy(self, deep=False, copy_technology=False)

Create a copy of this reference.

Args

• 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

Reference: New copy.

get_labels

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

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

Args

• 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[Label]: List of labels.

get_ports

get_ports(self, port_name=None)

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

Args

• 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

list[Port | FiberPort | GaussianPort] | dict[str, list[Port | FiberPort | GaussianPort]]: 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

get_repetition(self, repetition_index=-1)

Create new references by applying the repetition in this reference.

Args

• repetition_index (int): If non-negative, only the repetition with the given index is created. Otherwise, all repetitions are returned in a list.

Returns

Reference | list[Reference]: New reference or reference list.

get_structures

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

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

Args

• 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[Rectangle | Circle | Polygon | Path]: List of structures.

get_terminals

get_terminals(self, terminal_name=None)

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

Args

• 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

list[Terminal] | dict[str, list[Terminal]]: 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

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

Mirror this reference.

Args

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

Returns

Reference: This reference.

query

query(self, *args)

Query ports and terminals from the reference or its dependencies.

Args

• *args (str | int | None): Strings, integers or None representing a reference specification ending with a port/terminal specification (see below for further information).

Returns

Port | FiberPort | GaussianPort | Terminal | list[Port | FiberPort | GaussianPort | Terminal]: 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.

See Also

Examples in Component.query.

rotate

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

Rotate this reference around a specific center.

Args

• rotation (float): Rotation angle in degrees.
• center (Sequence[float] | complex): Center of rotation.

Returns

Reference: This reference.

scale

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

Scale this reference.

Args

• scaling (float): Scaling factor.
• center (Sequence[float] | complex): Center of scaling.

Returns

Reference: This reference.

size

size(self, include_labels=True)

Calculate the reference size.

Args

• include_labels (bool): If set, include labels.

Returns

ndarray: The reference size.

transform

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

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

Args

• translation (Sequence[float] | complex): Translation vector.
• rotation (float): Rotation angle in degrees.
• scaling (float): Magnification factor.
• x_reflection (bool): Mirror across the horizontal axis.

Returns

Reference: This reference.

transformed_component

transformed_component(self, name, repetition_index=0)

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

Args

• name (str): New component name.
• repetition_index (int): For reference arrays, which element in the repetition to use.

Returns

Component: New component.

translate

translate(self, translation)

Translate this reference.

Args

• translation (Sequence[float] | complex): Translation vector.

Returns

Reference: This reference.

update

update(
    self,
    technology_updates={},
    component_updates={},
    model_updates={},
    chain_technology_updates=True,
    classification='optical',
)

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.

Args

• technology_updates (dict[str, object]): Updates to the technology of the referenced component. The values in this dictionary take precedence over Reference.technology_updates.
• component_updates (dict[str, object]): Updates to the referenced component. The values in this dictionary take precedence over Reference.component_updates.
• model_updates (dict[str, object]): Updates to the model of the referenced component. The values in this dictionary take precedence over Reference.model_updates.
• chain_technology_updates (bool): if set, a technology update will trigger an update for all components using that technology.
• classification (Literal[“electrical”, “optical”]): Classification of the returned ports.

Returns

list[tuple[Technology | Component | Model, dict[str, object]]]: List of tuples with the updated objects and their original parametric keyword arguments, in the order they were updated.

Note

Because components have multiple models, model_updates can be specified per model as a dictionary of keyword arguments using the model names as keys. Only the currently active component model will be updated.

In this example, only the "Waveguide" model (default model for the bend) is updated:

>>> component = pf.parametric.bend(port_spec="Strip", radius=10)
>>> reference = pf.Reference(component)
>>> model_updates = {
...     "Waveguide": {"length": 1.0},  # Updates for Waveguide model
...     "Tidy3D": {"verbose": False},  # Updates for Tidy3D model
... }
>>> reference.update(model_updates=model_updates)
[(WaveguideModel(n_complex=None, length=1.0, ...), {...})]

See Also

Circuit Model guide

Attributes

Attribute	Description
columns	int: Number of reference columns.
component	Component: Referenced component.
component_name	str: Name of the referenced component (read only).
component_updates	dict[str, object]: Keyword arguments used for calling Component.update before calculating the S matrix from a CircuitModel.
model_updates	dict[str, object]: Keyword arguments used for calling Model.update before calculating the S matrix from a CircuitModel.
origin	ndarray: Reference origin.
properties	Properties: Object properties.
rotation	float: Reference rotation.
rows	int: Number of reference rows.
s_matrix_kwargs	dict[str, object]: Keyword arguments used when calling Component.s_matrix from a CircuitModel.
scaling	float: Reference scaling.
spacing	ndarray: Spacing between reference columns and rows.
technology_updates	dict[str, object]: Keyword arguments used for calling Technology.update before calculating the S matrix from a CircuitModel.
time_stepper_kwargs	dict[str, object]: Keyword arguments used when setting up a time stepper from a CircuitModel (e.g. a per-reference carrier frequency and fit grid).
x_max	float: Upper bound in the x axis.
x_mid	float: Bounding box center in the x axis.
x_min	float: Lower bound in the x axis.
x_reflection	bool: Reference x_reflection.
y_max	float: Upper bound in the y axis.
y_mid	float: Bounding box center in the y axis.
y_min	float: Lower bound in the y axis.

columns

int: Number of reference columns.

component

Component: Referenced component.

component_name

str: Name of the referenced component (read only).

component_updates

dict[str, object]: Keyword arguments used for calling Component.update before calculating the S matrix from a CircuitModel.

model_updates

dict[str, object]: Keyword arguments used for calling Model.update before calculating the S matrix from a CircuitModel.

origin

ndarray: Reference origin.

properties

Properties: Object properties.

rotation

float: Reference rotation.

rows

int: Number of reference rows.

s_matrix_kwargs

dict[str, object]: Keyword arguments used when calling Component.s_matrix from a CircuitModel.

scaling

float: Reference scaling.

spacing

ndarray: Spacing between reference columns and rows.

technology_updates

dict[str, object]: Keyword arguments used for calling Technology.update before calculating the S matrix from a CircuitModel.

time_stepper_kwargs

dict[str, object]: Keyword arguments used when setting up a time stepper from a CircuitModel (e.g. a per-reference carrier frequency and fit grid).

x_max

float: Upper bound in the x axis.

x_mid

float: Bounding box center in the x axis.

x_min

float: Lower bound in the x axis.

x_reflection

bool: Reference x_reflection.

y_max

float: Upper bound in the y axis.

y_mid

float: Bounding box center in the y axis.

y_min

float: Lower bound in the y axis.