reference_chain

photonforge.reference_chain(components, sequence, start=None)[source]

Create a chain of connected references from a text sequence.

Parameters:

  • components (dict[str, Component | tuple[Component, str, str]]) – 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 (str) – Chain description with elements separated by "-". Whitespace is ignored. See the element syntax below.

  • start (Port | None) – 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.

Return type:

list[Reference]

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.