Utilities¶

lightworks.random_unitary(N: int, seed: int | None = None) → ndarray[Any, dtype[complex128]]¶

Generate a random NxN unitary matrix. Seed can be used to produce the same unitary each time the function is called.

Parameters:

N (int) – The dimension of the random unitary that is to be generated.
seed (int | None, optional) – Specify a random seed to repeatedly produce the same unitary matrix on each function call. Defaults to None, which will produce a random matrix on each call.

Returns:

The created random unitary matrix.

Return type:

np.ndarray

lightworks.random_permutation(N: int, seed: int | None = None) → ndarray[Any, dtype[complex128]]¶

Generate a random NxN permutation. Seed can be used to produce the same unitary each time the function is called.

Parameters:

N (int) – The dimension of the random permutation that is to be generated.
seed (int | None, optional) – Specify a random seed to repeatedly produce the same unitary matrix on each function call. Defaults to None, which will produce a random matrix on each call.

Returns:

The created random permutation matrix.

Return type:

np.ndarray

class lightworks.convert¶

Contains a range of functions for converting/mapping between quantities.

static db_loss_to_decimal(loss: float) → float¶

Function to convert from a given dB loss into the equivalent loss value in decimal form. Note this function does not support conversion of gain values.

Parameters:: loss (float) – The loss value in decibels.
Returns:: The calculated loss as a decimal.
Return type:: float

static decimal_to_db_loss(loss: float) → float¶

Function to convert from a decimal into dB loss. This dB loss will be returned as a positive value.

Parameters:

loss (float) – The loss value as a decimal, this should be in the range [0,1).

Returns:

The calculated dB loss. This is returned as a positive: value.

Return type:

float

Raises:

ValueError – Raised in cases where transmission is not in range [0,1).

static dual_rail_to_qubit(state: State | list[int], allow_invalid: bool = False) → State¶

Converts from a dual-rail encoded Fock state into the qubit encoded equivalent.

Parameters:

state (State) – The dual-rail state to convert. This state should contain a single photon between pairs of adjacent modes.
allow_invalid (bool) – Controls whether or not invalid values are supported for a qubit. In these cases, the numerical value will be replaced by an X.

Returns:

The calculated qubit state.

Return type:

State

Raises:

ValueError – Raised when an invalid state is provided for conversion.

static parity_mapping(state: State, invert: bool = False) → State¶

Apply a parity mapping to a State, in which the state values are converted to either 0 or 1 depending on if the value is odd or even.

Parameters:

state (State) – The state to be converted.
invert (bool, optional) – Select whether to invert the parity mapping. This will swap between even->0 & odd->1 and even->1 & odd->0.

Returns:

The parity mapped state.

Return type:

State

static qubit_to_dual_rail(state: State | list[int] | str) → State¶

Converts from a qubit encoding into a dual-rail encoded state between modes.

Parameters:: state (State) – The qubit state to convert.
Returns:: The dual-rail encoded Fock state.
Return type:: State
Raises:: ValueError – Raised when values in the original state aren’t either 0 or 1.

static threshold_mapping(state: State, invert: bool = False) → State¶

Apply a threshold mapping to a State, in which any values above 1 will be reduced to 1.

Parameters:

state (State) – The state to be converted.
invert (bool, optional) – Select whether to invert the threshold mapping. This will swap the 0s and 1s of the produced states.

Returns:

The threshold mapped state.

Return type:

State

class lightworks.PostSelection(multi_rules: bool = False)¶

Post-selection

Parameters:: multi_rules (bool, optional) – Controls whether multiple rules can be applied to a single mode.

add(modes: int | tuple[int, ...], n_photons: int | tuple[int, ...]) → None¶

Adds a post-selection rule across the provided modes, conditioning that the total number of photons across the modes is equal to any of the provided number of photons.

Parameters:

modes (int, tuple) – The modes across which post-selection should be applied. This can be a singular mode provided as an integer or a range of modes as a tuple.
n_photons (int, tuple) – The valid photon number totals across the modes. This can be a singular integer value or a range of allowable photon numbers.

property modes: list[int]¶: Returns modes on which rules are currently applied.

property rules: list[Rule]¶: Returns currently applied post-selection rules.

validate(state: State | list[int]) → bool¶

Validates whether a provided State meets the set post-selection criteria.

Parameters:

state (State) – The state which is to be checked.

Returns:

Indicates whether the provided State meets the post-selection: criteria.

Return type:

bool

class lightworks.PostSelectionFunction(function: Callable[[State], bool])¶

Allows for post-selection to be implemented with a provided function.

validate(state: State | list[int]) → bool¶

Validates whether a provided State meets the set post-selection criteria.

Parameters:

state (State) – The state which is to be checked.

Returns:

Indicates whether the provided State meets the post-selection: criteria.

Return type:

bool