PhotonicCircuit

class lightworks.PhotonicCircuit(n_modes: int)

Provides support for building photonic circuits from a set of linear optic components, with the ability to assign certain quantities of components to Parameter objects whose values can be adjusted after creation.

Parameters:

n_modes (int) – The number of modes used in the circuit.

property U: ndarray[Any, dtype[complex128]]

The effective unitary that the circuit implements across modes. This will include the effect of any loss within a circuit. It is calculated using the parameter values at the time that the attribute is called.

property U_full: ndarray[Any, dtype[complex128]]

The full unitary for the created circuit, this will include the additional modes used for the simulation of loss, if this has been included in the circuit.

add(circuit: PhotonicCircuit | Unitary, mode: int = 0, group: bool = False, name: str | None = None) → None

Can be used to add either another PhotonicCircuit or a Unitary component to the existing circuit. This can either have the same size or be smaller than the circuit which is being added to.

Parameters:

• circuit (PhotonicCircuit | Unitary) – The circuit/component that is to be added.

• mode (int, optional) – The first mode on which the circuit should be placed. If not specified it defaults to zero.

• group (bool, optional) – Used to control whether the circuit components are added to the existing circuit or placed within a group which contains all components in a single element. Defaults to False unless the added circuit has heralds, in which grouping is enforced.

• name (str | None, optional) – Set a name to use when displaying the added circuit. This is only applied when the group option is used.

barrier(modes: list[int] | None = None) → None

Adds a barrier to separate different parts of a circuit. This is applied to the specified modes.

Parameters:

modes (list | None) – The modes over which the barrier should be applied to.

bs(mode_1: int, mode_2: int | None = None, reflectivity: float = 0.5, loss: float = 0, convention: str = 'Rx') → None

Add a beam splitter of specified reflectivity between two modes to the circuit.

Parameters:

• mode_1 (int) – The first mode which the beam splitter acts on.

• mode_2 (int | None, optional) – The second mode that the beam splitter acts on. This can also be left as the default value of None to automatically use mode_2 as mode_1 + 1.

• reflectivity (float, optional) – The reflectivity value of the beam splitter. Defaults to 0.5.

• loss (float, optional) – The loss of the beam splitter, this should be provided as a decimal value in the range [0,1].

• convention (str, optional) – The convention to use for the beam splitter, should be either “Rx” (the default value) or “H”.

compress_mode_swaps() → None

Takes a provided circuit spec and will try to compress any more swaps such that the circuit length is reduced. Note that any components in a group will be ignored.

copy(freeze_parameters: bool = False) → PhotonicCircuit

Creates and returns an identical copy of the circuit, optionally freezing parameter values.

Parameters:

freeze_parameters (bool, optional) – Used to control where any existing parameter objects are carried over to the newly created circuit, or if the current parameter values should be used. Defaults to False.

Returns:

A new PhotonicCircuit object with the same

circuit configuration as the original object.

Return type:

PhotonicCircuit

display(show_parameter_values: bool = False, display_loss: bool = False, mode_labels: list[str] | None = None, display_type: str = 'svg') → None

Displays the current circuit with parameters set using either their current values or labels.

Parameters:

• show_parameter_values (bool, optional) – Shows the values of parameters instead of the associated labels if specified.

• display_loss (bool, optional) – Choose whether to display loss components in the figure, defaults to False.

• mode_labels (list|None, optional) – Optionally provided a list of mode labels which will be used to name the mode something other than numerical values. Can be set to None to use default values.

• display_type (str, optional) – Selects whether the drawsvg or matplotlib module should be used for displaying the circuit. Should either be ‘svg’ or ‘mpl’, defaults to ‘svg’.

get_all_params() → list[Parameter[Any]]

Returns all the Parameter objects used as part of creating the circuit.

herald(n_photons: int, input_mode: int, output_mode: int | None = None) → None

Add a herald across a selected input/output of the circuit. If only one mode is specified then this will be used for both the input and output.

Parameters:

• n_photons (int) – The number of photons to use for the heralding.

• input_mode (int) – The input mode to use for the herald.

• output_mode (int | None, optional) – The output mode for the herald, if this is not specified it will be set to the value of the input mode.

property heralds: dict[str, dict[int, int]]

A dictionary which details the set heralds on the inputs and outputs of the circuit.

property input_modes: int

The number of input modes that should be specified, accounting for the heralds used in the circuit.

loss(mode: int, loss: float = 0) → None

Adds a loss channel to the specified mode of the circuit.

Parameters:

• mode (int) – The mode on which the loss channel acts.

• loss (float, optional) – The loss applied to the selected mode, this should be provided as a decimal value in the range [0,1].

mode_swaps(swaps: dict[int, int]) → None

Performs swaps between a given set of modes. The keys of the dictionary should correspond to the initial modes and the values to the modes they are swapped to. It is also required that all mode swaps are complete, i.e. any modes which are swapped to must also be sent to a target destination.

Parameters:

swaps (dict) – A dictionary detailing the original modes and the locations that they are to be swapped to.

property n_modes: int

The number of modes in the circuit.

ps(mode: int, phi: float, loss: float = 0) → None

Applies a phase shift to a given mode in the circuit.

Parameters:

• mode (int) – The mode on which the phase shift acts.

• phi (float) – The angular phase shift to apply.

• loss (float, optional) – The loss of the phase shifter, this should be provided as a decimal value in the range [0,1].

remove_non_adjacent_bs() → None

Removes any beam splitters acting on non-adjacent modes by replacing with a mode swap and adjacent beam splitters.

unpack_groups() → None

Unpacks any component groups which may have been added to the circuit.