Skip to content
PhotonForge

reference_chain

reference_chain(
    components: dict[
        str, photonforge.Component | tuple[photonforge.Component, str, str]
    ],
    sequence: str,
    start: photonforge.Port | None = None,
) -> list[photonforge.Reference]

Create a chain of connected references from a text sequence.

Args

  • components: Mapping from the symbols used in sequence to components or to (component, input_port, output_port) tuples, which set the default ports for that symbol.
  • sequence: Chain description with elements separated by "-". Whitespace is ignored. See the element syntax below.
  • start: Port to connect the first element to. If None, the first reference is not transformed.

Returns

References in chain order, each connected to the previous one.

Examples

>>> wg = parametric.straight(port_spec="Strip", length=10)
>>> arc = parametric.bend(port_spec="Strip", radius=5)
>>> references = reference_chain(
...     {"wg": wg, "arc": arc},
...     "wg - (arc - wg*2)*2 - !arc - 5 - P1:wg",
... )
>>> component = Component("CHAIN").add(*references)
>>> component.add_port([references[0]["P0"], references[-1]["P0"]])
['P0', 'P1']

Each element in the sequence can be:

  • symbol: instance of components[symbol] using its default ports: the ones in the components tuple or, otherwise, the first 2 ports in natural sort order as input and output.
  • in:symbol, symbol:out, or in:symbol:out: instance with explicit input and/or output ports. Unspecified roles take the remaining ports, default ones first, then in natural order, so "P1:wg" reverses a 2-port component. A component with a single port uses it for both roles.
  • !symbol: mirrored instance, also valid with explicit ports, as in "P1:!symbol".
  • element*N: N repetitions of the element. N >= 0.
  • (sequence)*N: N repetitions of the sub-sequence. N >= 0.
  • A number: spacer of that length, using parametric.straight if the neighboring ports can be connected, or parametric.transition otherwise. Consecutive spacers are merged. A spacer requires a neighboring component or start.